Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DNSSEC-KEYGEN(8)		    BIND 9		      DNSSEC-KEYGEN(8)

NAME
       dnssec-keygen - DNSSEC key generation tool

SYNOPSIS
       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/off-
       set] [-P	sync date/offset] [-p protocol]	[-q] [-R date/offset] [-S key]
       [-s strength] [-T rrtype] [-t type] [-V]	[-v level] {name}

DESCRIPTION
       dnssec-keygen generates keys for	DNSSEC (Secure DNS), as	defined	in RFC
       2535  and RFC 4034. It can also generate	keys for use with TSIG (Trans-
       action Signatures) as defined in	RFC 2845, or TKEY (Transaction Key) as
       defined in RFC 2930.

       The  name of the	key is specified on the	command	line. For DNSSEC keys,
       this must match the name	of the zone for	which the key is being	gener-
       ated.

       The  dnssec-keymgr command acts as a wrapper around dnssec-keygen, gen-
       erating and updating keys as needed to enforce defined  security	 poli-
       cies  such  as  key  rollover  scheduling.  Using  dnssec-keymgr	may be
       preferable to direct use	of dnssec-keygen.

OPTIONS
       -3     This option uses an NSEC3-capable	algorithm to generate a	DNSSEC
	      key. If this option is used with an algorithm that has both NSEC
	      and NSEC3	versions, then the NSEC3 version is selected; for  ex-
	      ample,  dnssec-keygen -3a	RSASHA1	specifies the NSEC3RSASHA1 al-
	      gorithm.

       -a algorithm
	      This option selects  the	cryptographic  algorithm.  For	DNSSEC
	      keys,   the   value   of	algorithm  must	 be  one  of  RSASHA1,
	      NSEC3RSASHA1,  RSASHA256,	  RSASHA512,   ECDSAP256SHA256,	  ECD-
	      SAP384SHA384,  ED25519, or ED448.	For TKEY, the value must be DH
	      (Diffie-Hellman);	specifying this	value automatically  sets  the
	      -T KEY option as well.

	      These  values are	case-insensitive. In some cases, 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  op-
	      tion, which copies the algorithm from the	predecessor key.

	      In prior releases, HMAC algorithms could be generated for	use as
	      TSIG keys, but that feature was  removed	in  BIND  9.13.0.  Use
	      tsig-keygen to generate TSIG keys.

       -b keysize
	      This  option specifies the number	of bits	in the key. The	choice
	      of key size depends on the algorithm used: RSA keys must be  be-
	      tween  1024  and	4096 bits; Diffie-Hellman keys must be between
	      128 and 4096 bits. Elliptic curve	algorithms do  not  need  this
	      parameter.

	      If  the  key size	is not specified, some algorithms have pre-de-
	      fined  defaults.	For  example,  RSA  keys  for  use  as	DNSSEC
	      zone-signing keys	have a default size of 1024 bits; RSA keys for
	      use as key-signing keys (KSKs, generated with -f KSK) default to
	      2048 bits.

       -C     This  option  enables  compatibility  mode,  which  generates an
	      old-style	 key,  without	any  timing  metadata.	 By   default,
	      dnssec-keygen  includes  the key's creation date in the metadata
	      stored with the private key; other dates may  be	set  there  as
	      well,  including	publication  date,  activation date, etc. Keys
	      that include this	data may be incompatible with  older  versions
	      of BIND; the -C option suppresses	them.

       -c class
	      This  option  indicates  that  the DNS record containing the key
	      should have the specified	class. If not specified, class	IN  is
	      used.

       -d bits
	      This  option  specifies the key size in bits. For	the algorithms
	      RSASHA1, NSEC3RSASA1, RSASHA256, and RSASHA512 the key size must
	      be  between  1024	and 4096 bits; DH size is between 128 and 4096
	      bits. This option	is  ignored  for  algorithms  ECDSAP256SHA256,
	      ECDSAP384SHA384, ED25519,	and ED448.

       -E engine
	      This  option  specifies  the cryptographic hardware to use, when
	      applicable.

	      When BIND	9 is built with	OpenSSL, this needs to be set  to  the
	      OpenSSL engine identifier	that drives the	cryptographic acceler-
	      ator or hardware service module (usually pkcs11).	When  BIND  is
	      built with native	PKCS#11	cryptography (--enable-native-pkcs11),
	      it defaults to the path of the PKCS#11 provider  library	speci-
	      fied via --with-pkcs11.

       -f flag
	      This  option  sets  the  specified flag in the flag field	of the
	      KEY/DNSKEY record.  The only recognized flags are	KSK (Key-Sign-
	      ing Key) and REVOKE.

       -G     This  option  generates  a  key, but does	not publish it or sign
	      with it. This option is incompatible with	-P and -A.

       -g generator
	      This option indicates the	 generator  to	use  if	 generating  a
	      Diffie-Hellman  key. Allowed values are 2	and 5. If no generator
	      is specified, a known prime from RFC 2539	is used	 if  possible;
	      otherwise	the default is 2.

       -h     This  option prints a short summary of the options and arguments
	      to dnssec-keygen.

       -K directory
	      This option sets the directory in	which the key files are	to  be
	      written.

       -k policy
	      This option creates keys for a specific dnssec-policy. If	a pol-
	      icy uses multiple	keys, dnssec-keygen generates  multiple	 keys.
	      This  also  creates  a  ".state"	file  to keep track of the key
	      state.

	      This option creates keys according to the	dnssec-policy configu-
	      ration,  hence it	cannot be used at the same time	as many	of the
	      other options that dnssec-keygen provides.

       -L ttl This option sets the default TTL to use for this key when	it  is
	      converted	into a DNSKEY RR. This is the TTL used when the	key is
	      imported into a zone, unless there was already a DNSKEY RRset in
	      place,  in which case the	existing TTL takes precedence. If this
	      value is not set and there is no existing	DNSKEY RRset, the  TTL
	      defaults to the SOA TTL. Setting the default TTL to 0 or none is
	      the same as leaving it unset.

       -l file
	      This option  provides  a	configuration  file  that  contains  a
	      dnssec-policy statement (matching	the policy set with -k).

       -n nametype
	      This  option  specifies  the owner type of the key. The value of
	      nametype	must  either  be  ZONE	(for   a   DNSSEC   zone   key
	      (KEY/DNSKEY)),  HOST or ENTITY (for a key	associated with	a host
	      (KEY)), USER (for	a key associated with a	user (KEY)), or	 OTHER
	      (DNSKEY).	These values are case-insensitive. The default is ZONE
	      for DNSKEY generation.

       -p protocol
	      This option sets the protocol value for the generated  key,  for
	      use with -T KEY. The protocol is a number	between	0 and 255. The
	      default is 3 (DNSSEC). Other possible values for	this  argument
	      are listed in RFC	2535 and its successors.

       -q     This  option  sets quiet mode, which suppresses unnecessary out-
	      put, including progress indication. Without  this	 option,  when
	      dnssec-keygen is run interactively to generate an	RSA or DSA key
	      pair, it prints a	string of symbols  to  stderr  indicating  the
	      progress of the key generation. A	. indicates that a random num-
	      ber has been found which passed an initial sieve test; + means a
	      number  has  passed a single round of the	Miller-Rabin primality
	      test; and	a space	( ) means that the number has passed  all  the
	      tests and	is a satisfactory key.

       -S key This  option 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 the existing one. The
	      publication date is set to the activation	date minus the prepub-
	      lication interval, which defaults	to 30 days.

       -s strength
	      This option  specifies  the  strength  value  of	the  key.  The
	      strength	is a number between 0 and 15, and currently has	no de-
	      fined purpose in DNSSEC.

       -T rrtype
	      This option specifies the	resource record	type to	 use  for  the
	      key.  rrtype must	be either DNSKEY or KEY. The default is	DNSKEY
	      when using a DNSSEC algorithm, but it can	be overridden  to  KEY
	      for use with SIG(0).

       -t type
	      This  option  indicates the type of the key for use with -T KEY.
	      type must	be one of AUTHCONF, NOAUTHCONF,	NOAUTH,	or NOCONF. The
	      default  is AUTHCONF. AUTH refers	to the ability to authenticate
	      data, and	CONF to	the ability to encrypt data.

       -V     This option prints version information.

       -v level
	      This option sets the debugging level.

TIMING OPTIONS
       Dates can be expressed in the format YYYYMMDD or	YYYYMMDDHHMMSS.	If the
       argument	 begins	with a + or -, it is interpreted as an offset from the
       present time. For convenience, 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  (de-
       fined  as  30  24-hour  days),  weeks, days, hours, or minutes, respec-
       tively. Without a suffix, the offset is computed	in seconds. To explic-
       itly prevent a date from	being set, use none or never.

       -P date/offset
	      This  option  sets the date on which a key is to be published to
	      the zone.	After that date, the key is included in	the  zone  but
	      is not used to sign it. If not set, and if the -G	option has not
	      been used, the default is	the current date.

       -P sync date/offset
	      This option sets the date	on which CDS and CDNSKEY records  that
	      match this key are to be published to the	zone.

       -A date/offset
	      This  option  sets the date on which the key is to be activated.
	      After that date, the key is included in the  zone	 and  used  to
	      sign it. If not set, and if the -G option	has not	been used, the
	      default is the current date. If set, and -P is not set, the pub-
	      lication	date is	set to the activation date minus the prepubli-
	      cation interval.

       -R date/offset
	      This option sets the date	on which the key is to be revoked. Af-
	      ter  that	date, the key is flagged as revoked. It	is included in
	      the zone and is used to sign it.

       -I date/offset
	      This option sets the date	on which the key is to be retired. Af-
	      ter  that	date, the key is still included	in the zone, but it is
	      not used to sign it.

       -D date/offset
	      This option sets the date	on which the key is to be deleted. Af-
	      ter  that	date, the key is no longer included in the zone. (How-
	      ever, it may 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 are to be deleted.

       -i interval
	      This  option sets	the prepublication interval for	a key. If set,
	      then the publication and activation dates	must be	 separated  by
	      at least this much time. If the activation date is specified but
	      the publication date is not, the publication  date  defaults  to
	      this  much  time	before the activation date; conversely,	if the
	      publication date is specified but	not the	activation date, acti-
	      vation is	set to this much time after publication.

	      If  the key is being created as an explicit successor to another
	      key, then	the default prepublication interval is 30 days;	other-
	      wise 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, respectively.
	      Without a	suffix,	the interval is	measured in seconds.

GENERATED KEYS
       When dnssec-keygen completes successfully, it prints a  string  of  the
       form Knnnn.+aaa+iiiii to	the standard output. This is an	identification
       string for the key it has generated.

       o nnnn is the key name.

       o aaa is	the numeric representation of the algorithm.

       o iiiii is the key identifier (or footprint).

       dnssec-keygen creates two  files,  with	names  based  on  the  printed
       string.	  Knnnn.+aaa+iiiii.key	  contains   the   public   key,   and
       Knnnn.+aaa+iiiii.private	contains the private key.

       The .key	file contains a	DNSKEY or KEY record. When  a  zone  is	 being
       signed  by named	or dnssec-signzone -S, DNSKEY records are included au-
       tomatically. 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 obvious secu-
       rity reasons, this file does not	have general read permission.

EXAMPLE
       To generate an ECDSAP256SHA256 zone-signing  key	 for  the  zone	 exam-
       ple.com,	issue the command:

       dnssec-keygen -a	ECDSAP256SHA256	example.com

       The command prints a string of the form:

       Kexample.com.+013+26160

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

       To generate a matching key-signing key, issue the command:

       dnssec-keygen -a	ECDSAP256SHA256	-f KSK example.com

SEE ALSO
       dnssec-signzone(8), BIND	9 Administrator	Reference  Manual,  RFC	 2539,
       RFC 2845, RFC 4034.

AUTHOR
       Internet	Systems	Consortium

COPYRIGHT
       2021, Internet Systems Consortium

9.16.21				  2021-09-07		      DNSSEC-KEYGEN(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | TIMING OPTIONS | GENERATED KEYS | EXAMPLE | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dnssec-keygen&sektion=8&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help