.png){kind=logo}
The ZoneHashSigner can be used to sign DNS zone zip files using the SignClient in client-side hashing and construction mode, contained in a zip file, using DNS Security Extensions (DNSSEC).
Fully qualified class name: org.signserver.module.dnssec.signer.ZoneHashSigner
Overview
For a guide on signing DNSSEC zone files with client-side hashing using the ZoneHash Signer, see Code Signing with Client-side Hashing.
The signer is designed around a two-stage request-response protocol, see Protocol.
To download a sample configuration file for this Worker, see Sample Worker Configurations.
For information on the interfaces this Worker can be called through, see Supported Interfaces by Worker.
Available Properties
|
Required Property |
Default |
Description |
|---|---|---|
|
|
None |
Specifies the active key signing keys to use. Must specify exactly 1 or 2 key aliases, comma-separated. Example: |
|
|
None |
Specifies the name of the top-level zone in the zone file. Example: |
|
|
None |
Specifies the key alias prefix to use for zone signing. The key used is based on the prefix with the key sequence number appended. Example: |
|
Property |
Default |
Description |
|
|
|
|
|
|
|
Disables the key usage counter. As the key usage counter is not supported by this Signer, if set, only the value |
|
|
None |
Specifies the fixed, HEX-encoded salt (64-bit value) to use instead of a random salt for testing/troubleshooting purposes. Example: |
|
|
|
Specifies if the previous ZSK (if one) should be kept published. |
|
|
|
Specifies the signature algorithm to use for all signatures. Only |
|
|
None |
Specifies maximum number of parallel signing tasks to run. The default behavior when not specified or set to |
Request Parameters
|
Property |
Description |
|---|---|
|
|
Specifies the TTL of the SOA (start of authority) record in seconds. This is only used for the pre-request. This property is required when sending the pre-request. |
|
|
Specifies the sequence number to append after key alias prefix. Example: |
Protocol
Due to the way DNSSEC zone file signing works, this Signer is designed around a two-stage request-response protocol.
|
Step |
Send |
Receive |
|---|---|---|
|
1 - Pre-sign |
Empty body + |
DNSKEY records, their signatures, and the NSEC3PARAM record |
|
2 - Sign |
Same |
One signature per hash, mapped back by ID |
Step 1 - Pre-sign
In the first request (pre-sign request), send an empty request body to indicate to the Signer that the request is a pre-request.
Include the request metadata parameters:
-
ZSK_SEQUENCE_NUMBER: Indicates the zone signing key sequence number to use. -
SOA_TTL: Provide the the TTL (Time To Live) of the SOA (Start of Authority) record.
Request
Request body:
<Empty>
Metadata:
ZSK_SEQUENCE_NUMBER=1, SOA_TTL=86400
Response
Signer sends back a pre-sign response with DNSKEY records, signature records for the DNSKEY records, and the NSEC3PARAM record encoded.
Example response body (Java properties file format):
rr.dnskey.z1.expiretime=1577011258284
rr.dnskey.z1.signingtime=1574419258284
rr.dnskey.z1.footprint=11644
rr.dnskey.z1.algorithm=8
rr.dnskey.z0=...base64 of wire format for DNSKEY 256 (if one)...
rr.dnskey.z1=...base64 of wire format for DNSKEY 256...
rr.dnskey.z2=...base64 of wire format for DNSKEY 256 (if one)...
rr.dnskey.k1=...base64 of wire format for DNSKEY 257...
rr.dnskey.k2=...base64 of wire format for DNSKEY 257 (if one)...
rr.dnskey.sig.z1=...base64 of wire format for RRSIG with Z1 key...
rr.dnskey.sig.k1=...base64 of wire format for RRSIG with K1 key...
rr.dnskey.sig.k2=...base64 of wire format for RRSIG with K2 key (if one)...
rr.nsec3param=...base64 of wire format for NSEC3PARAM...
rr.nsec3param.sig=...base64 of wire format for RRSIG of NSEC3PARAM...
Step 2 - Sign
Construct the sign request containing the same ZSK_SEQUENCE_NUMBER as in the pre-sign request, the same SIG record data as received from the pre-sign response, and mappings from each RRsetId to hash that should be signed. The hash is calculated using the SIG record data received in the pre-sign response and the RRset.
Request
Metadata:
ZSK_SEQUENCE_NUMBER=1, rr.dnskey.z1.expiretime=1577011258284, rr.dnskey.z1.signingtime=1574419258284, rr.dnskey.z1.footprint=11644, rr.dnskey.z1.algorithm=8
Body:
hash.1=...base64 of hash or signature input...
hash.2=...
hash.N=...
Response
The server verifies that the received footprint is correct and matches the ZSK_SEQUENCE_NUMBER. The server signs each hash and responds with a sign response containing a mapping from the same IDs provided in the sign request to the signature values.
The client matches sig.<id> back to hash.<id> and inserts each signature into the corresponding RRSIG record.
Response body (Java properties file format):
sig.1=...base64 of signature of hash.1...
sig.2=...
sig.N=...
End-to-end CLI Example
An example using SignClient signdocument command to sign the zone zip file:
$ signclient signdocument -workername ZoneHashSigner \
-clientside -digestalgorithm SHA-256 \
-filetype ZONE_ZIP \
-infile example.com.zone.zip \
-outfile example.com-signed.zone \
-metadata ZSK_SEQUENCE_NUMBER=1 \
-extraoption ZONE_NAME=example.com. \
-extraoption MIN_REMAINING_VALIDITY=86400