dnssec-keygen Command

Edit online

Purpose

Domain name system security extensions (DNSSEC) key generation tool.

Syntax

dnssec-keygen [-3] [-A date/offset] [-a algorithm] [-b keysize] [-C] [-c class] [-D date/offset] [-d bits] [-D sync date/offset] [-E engine] [-f flag] [-G] [-g generator] [-h] [-I date/offset] [-i interval] [-K directory] [-k policy] [-L ttl] [-l file] [-n nametype] [-P date/offset] [-P sync date/offset] [-p protocol] [-q] [-R date/offset] [-S key] [-s strength] [-T rrtype] [-t type] [-V] [-v level] [name]

Description

The dnssec-keygen command generates keys for DNSSEC (Secure DNS) as defined in RFC 2535 and RFC 4034. It also generates keys that are used with Transaction Signatures (TSIG) as defined in RFC 2845, or Transaction Key (TKEY) as defined in RFC 2930.

The name of the key is specified in the command line. For DNSSEC keys, this name of the key must match the name of the zone for which the key is generated.

Flags

Table 1. Flags
Item Description
-3 Generates a DNSSEC key by using an NSEC3-capable algorithm. If this option is used with an algorithm that has both the version of NSEC and NSEC3, the NSEC3 version is selected. For example, dnssec-keygen -3a RSASHA1 specifies the NSEC3RSASHA1 algorithm.
-a algorithm
Selects the cryptographic algorithm. For DNSSEC keys, the value of algorithm must be either of the following values:
  • RSASHA1
  • NSEC3RSASHA1
  • RSASHA256
  • RSASHA512
  • ECDSAP256SHA256
  • ECDSAP384SHA384
  • ED25519
  • ED448
For -T KEY, the value must be Diffie-Hellman (DH). If you specify this value, it automatically sets the -T KEY option also.

These values are case-insensitive. Sometimes, abbreviations are supported, such as ECDSA256 for ECDSAP256SHA256 and ECDSA384 for ECDSAP384SHA384. If RSASHA1 is specified along with the -3 option, NSEC3RSASHA1 is used instead.

This parameter must be specified except when using the -S option, which copies the algorithm from the predecessor key.

In prior releases, HMAC algorithms might be generated for use as TSIG keys, but that feature is removed in BIND 9.13.0. Use the tsig-keygen command to generate TSIG keys.
-b keysize

Specifies the number of bits in the key. The choice of the key size depends on the algorithm used. RSA keys must be in the range 1024-4096 bits, DH keys must be in the range 128-4096 bits. Elliptic curve algorithms do not need this parameter.

If the key size is not specified, some algorithms have pre-defined default values. For example, RSA keys that are used as DNSSEC zone-signing keys have a default size of 1024 bits. RSA keys that are used as key-signing keys (KSKs, generated with -f KSK) have a default size of 2048 bits.
-C Enables compatibility mode that generates an old-style key without any timing metadata. By default, the dnssec-keygen command includes the creation date of the key in the metadata that is stored with the private key. Other dates such as the publication date, activation date, can also be set. Keys that include this data might be incompatible with older versions of BIND. The -C option suppresses this data.
-c class Indicates that the Domain Name System (DNS) record that contains the key must have the specified class. If not specified, class IN is used.
-d bits Specifies the key size in bits. For the algorithms RSASHA1, NSEC3RSASA1, RSASHA256, and RSASHA512, the key size must be in the range 1024-4096 bits, DH size must be in the range 128-4096 bits. This option is ignored for algorithms ECDSAP256SHA256, ECDSAP384SHA384, ED25519, and ED448.
-E engine

Specifies the cryptographic hardware to use, when applicable.

When BIND 9 is built with OpenSSL, this option needs to be set to the OpenSSL engine identifier that drives the cryptographic accelerator or hardware service module (usually PKCS11).

-f flag Sets the specified flag in the flag field of the KEY or the DNSKEY record. The only recognized flag is KSK DNSKEY.
-G Generates a key, but does not publish it or sign with it. This option is incompatible with the -P and -A flags.
-g generator Indicates the generator that must be used to generate a DH key. Allowed values are 2 and 5. If no generator is specified, a known prime from RFC 2539 is used if possible, else the default value is 2.
-h Prints a short summary of the options and arguments of the dnssec-keygen command.
-K directory Sets the directory in which the key files must be written.
-k policy

Creates keys for a specific dnssec-policy configuration. If a policy uses multiple keys, the dnssec-keygen command generates multiple keys. This option also creates a .state file to track the key state.

This option creates keys according to the dnssec-policy configuration. Hence, it cannot be used at the same time as the other options that the dnssec-keygen command provides.
-L ttl Sets the default time-to-live (TTL) that is used for the DNSSEC key when it is converted into a DNSKEY resource record (RR). This TTL is used when the key is imported into a zone, unless a DNSKEY RR is already set. In this case, the existing TTL takes precedence. If this value is not set and if a DNSKEY RR set does not exist, the TTL defaults to the SOA TTL. If the default value of the TTL is set to 0 or none, it is the same as to leave the TTL unset.
-l file This option provides a configuration file that contains a dnssec-policy statement (matching the policy set with the -k flag).
-n nametype Specifies the owner type of the key. The value of the nametype must be one of the following values:
  • ZONE for a DNSSEC zone key (KEY or DNSKEY)
  • HOST
  • ENTITY for a key associated with a host (KEY)
  • USER for a key associated with a user (KEY)
  • OTHER (DNSKEY)
These values are case-insensitive. The default value is ZONE for DNSKEY generation.
-p protocol Sets the protocol value for the generated key. The protocol value is in the range 0-255. The default value is 3 (DNSSEC). Other possible values for this argument are listed in RFC 2535 and its successors.
-q Sets a quiet mode, which suppresses unnecessary output, including progress indication. If dnssec-keygen command is run interactively without using this option to generate a Rivest-Shamir-Adleman (RSA) or Digital Signature Algorithm (DSA) key pair, it prints a string of symbols to stderr. This indicates the progress of the key generation.
  • A period (.) indicates that a random number that passed an initial sieve test.
  • A plus sign (+) indicates that a number passed a single round of the Miller-Rabin primality test.
  • Space ( ) indicates that the number passed all tests and is a satisfactory key.
-S key Creates a new key, which is an explicit successor to an existing key. The name, algorithm, size, and type of the key are set to match the existing key. The activation date of the new key is set to the inactivation date of an existing key. The publication date is set to the activation date minus the pre-publication interval, which defaults to 30 days.
-s strength Specifies the strength value of the key. The strength is a number in the range 0-15, and currently has no defined purpose in the DNSSEC algorithm.
-T rrtype Specifies the resource record type that must be used for the key. The rrtype must be either DNSKEY or KEY. The default value is DNSKEY when you use a DNSSEC algorithm, but the value can be overridden to KEY when you want to use the SIG(0) key-pair.
-t type Indicates the use of the key. The type must be one of the following values:
  • AUTHCONF
  • NOAUTHCONF
  • NOAUTH
  • NOCONF
The default value is AUTHCONF. AUTH indicates the ability to authenticate data, and CONF indicates the ability to encrypt data.
-V Prints version information.
-v level Sets the debugging level.

Timing flags

Dates can be expressed in the format YYYYMMDD or YYYYMMDDHHMMSS. If the argument begins with a plus sign (+) or minus sign (-), it is interpreted as an offset from the present time. If such an offset is followed by one of the suffixes, y, mo, w, d, h, or mi, then the offset is computed in years (defined as 365 24-hour days, ignoring leap years), months (defined as 30 24-hour days), weeks, days, hours, or minutes. Without a suffix, the offset is computed in seconds. To explicitly prevent a date from being set, use none, never, or unset.

Table 2. Timing flags
Item Description
-P date/offset This option sets the date on which a key must be published to the zone. After that date, the key is included in the zone but is not used to sign the zone. If this option is not set, and if the -G option is not used, the default value is the current date.
-P sync date/offset This option sets the date on which the child delegation signer (CDS) and the child domain name server key (CDNSKEY) records that match this key must be published to the zone.
-A date/offset This option sets the date on which the key must be activated. After that date, the key is included in the zone and is used to sign the zone. If this option is not set, and if the -G option is not used, the default value is the current date. If this option is set, and the -P flag is not set, the publication date is set to the activation date minus the pre-publication interval.
-R date/offset This option sets the date on which the key must be revoked. After that date, the key is flagged as revoked. The key is still included in the zone and is used to sign the zone.
-I date/offset This option sets the date on which the key must be retired. After that date, the key is still included in the zone, but it is not used to sign the zone.
-D date/offset This option sets the date on which the key must be deleted. After that date, the key is not included in the zone. However, it might remain in the key repository.
-D sync date/offset This option sets the date on which the CDS and CDNSKEY records that match this key must be deleted.
-i interval This option sets the pre-publication interval for a key. If this option is set, the publication and activation dates is separated by the specified time. If the activation date is specified but the publication date is not specified, the publication date defaults to the specified time before the activation date. Conversely, if the publication date is specified but the activation date is not specified, activation is set to the specified time after publication.

If the key is created as an explicit successor to another key, the default pre-publication interval is 30 days, else it is zero.

As with date offsets, if the argument is followed by one of the suffixes, y, mo, w, d, h, or mi, the interval is measured in years, months, weeks, days, hours, or minutes. Without a suffix, the interval is measured in seconds.

Parameters

Table 3. Parameters
Item Description
name The name of the key that is specified on the command line. For DNSSEC keys, this name must match the name of the zone for which the key is generated.

Generated keys

When the dnssec-keygen command completes successfully, it prints a string that is in the format Knnnn.+aaa+iiiii to the standard output. It is an identification string for the key that it generated.
  • nnnn is the key name.
  • aaa is the numeric representation of the algorithm.
  • iiiii is the key identifier (or footprint).
The dnssec-keygen command creates two files. The file name that is based on the printed string. The Knnnn.+aaa+iiiii.key contains the public key, and the file name that is based on the printed string. The Knnnn.+aaa+iiiii.private contains the private key.

The .key file contains a DNSKEY or KEY record. When a zone is signed by the named command or by using the dnssec-signzone -S command, the DNSKEY records are included automatically. In other cases, the .key file can be inserted into a zone file manually or with an $INCLUDE statement.

The .private file contains algorithm-specific fields. For security reasons, this file does not have general read permission.

Examples

To generate an ECDSAP256SHA256 zone-signing key for the zone example.com, enter the following command:
dnssec-keygen -a ECDSAP256SHA256 example.com
The command prints a string of the following format:
Kexample.com.+013+26160

In this example, the dnssec-keygen command creates the files Kexample.com.+013+26160.key and Kexample.com.+013+26160.private.

To generate a matching key-signing key, enter the following command:
dnssec-keygen -a ECDSAP256SHA256 -f KSK example.com