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=...