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

Required Property

Description

ACTIVE_KSKS

Specifies the active key signing keys to use. Must specify exactly 1 or 2 key aliases, comma-separated.

Example: example.com_K_1,example.com_K_2

ZONE_NAME

Specifies the name of the top-level zone in the zone file.

Example: example.com

ZSK_KEY_ALIAS_PREFIX

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: example.com_Z_

Property

Description

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.

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.

NSEC3_SALT

(Optional) Specifies the fixed, HEX-encoded salt (64-bit value) to use instead of a random salt for testing/troubleshooting purposes.

Example: 6dcd4ce23d88e2ee

PUBLISH_PREVIOUS_ZSK

(Optional) Specifies if the previous ZSK (if one) should be kept published.

Default: True.

SIGNATUREALGORITHM

Specifies the signature algorithm to use for all signatures. Only SHA1withRSA, SHA256withRSA, and SHA512withRSA are supported. All signature algorithms map to DNSSEC algorithms using NSEC3.

Default: SHA256withRSA

Request Parameters

Property

Description

SOA_TTL

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.

ZSK_SEQUENCE_NUMBER

Specifies the sequence number to append after key alias prefix.

Example: 1

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