ZoneHashSigner
The ZoneHashSigner signer has the fully qualified class name: org.signserver.module.dnssec.signer.ZoneHashSigner
Overview
The ZoneHashSigner signer 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).
For information on invoking the SignClient, see DNSSEC Signing in Client-Side Hashing.
The signer is designed around a two-stage request-response protocol, see Protocol.
Available Properties
| Property | Description |
|---|---|
| ZSK_KEY_ALIAS_PREFIX | Key alias prefix to use for zone signing. The key used will be based on the prefix with the key sequence number appended. Required. Example: "example.com_Z_". |
| ACTIVE_KSKS | Active key signing keys to use. Must specify exactly 1 or 2 key aliases, comma-separated. Required. Example: "example.com_K_1,example.com_K_2". |
| ZONE_NAME | The name of the top-level zone in the zone file. Required. Example: "example.com.". |
| PUBLISH_PREVIOUS_ZSK | If the previous ZSK (if one) should be kept published. Optional. Example: "false". Default: "true". |
| NSEC3_SALT | Fixed, hex-encoded salt (64-bit value) to use instead of a random salt for testing/troubleshooting purposes. Optional. Example: "6dcd4ce23d88e2ee". |
| DISABLEKEYUSAGECOUNTER | Disables the key usage counter. As the key usage counter is not supported by this signer, if set, only the value "true" is supported. |
| SIGNATUREALGORITHM | Signature algorithm to use for all signatures. Default: "SHA256withRSA". Currently only "SHA256withRSA is supported. All signature algorithms map to DNSSEC algorithms using NSEC3 and the NONEwithRSA algorithm is used for signing the digests. |
| CHECK_ACTIVE_KSKS | True if the keys configured in ACTIVE_KSKS should be checked for existence. Setting CHECK_ACTIVE_KSKS to "false" can improve performance in some environments when listing zone file signers in AdminWeb and when calling health check. Default: "true". |
Request Parameters
| Property | Description |
|---|---|
| ZSK_SEQUENCE_NUMBER | Sequence number to append after key alias prefix. Example: "1". |
| SOA_TTL | Specify 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. |
Protocol
Due to the way DNSSEC zone file signing works, this signer is designed around a two-stage request-response protocol.
In the first request (pre-sign request), the request body is empty (this tells the signer that the request is a pre-request). The request metadata parameters ZSK_SEQUENCE_NUMBER and SOA_TTL are included to indicate the zone signing key sequence number to use and the TTL (Time To Live) of the SOA (Start of Authority) record.
The signer sends back a pre-sign response with DNSKEY records, signature records for the DNSKEY records, and the NSEC3PARAM record. These are encoded in the response in the format of a Java properties file.
The client will then 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. 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 ID:s provided in the sign request to the signature values. The response data is formatted as a Java properties file. The receiving client (for example, the SignClient) then constructs each SIG record and inserts the signature received from the server.
Pre-sign request
- Metadata
ZSK_SEQUENCE_NUMBER=1, SOA_TTL=86400
- Request body
<Empty>
Pre-sign response
- Response body
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...
Sign request
- Metadata
ZSK_SEQUENCE_NUMBER=10, rr.dnskey.z1.expiretime=1577011258284, rr.dnskey.z1.signingtime=1574419258284, rr.dnskey.z1.footprint=11644, rr.dnskey.z1.algorithm=8
Request body
hash.1=...base64 of hash or signature input...
hash.2=...
hash.N=...
Sign response
- Response body
sig.1=...base64 of signature of hash.1... sig.2=... sig.N=...