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

FreeBSD Manual Pages

  
 
  

home | help 
COREDNS-SIGN(7)			CoreDNS	Plugins		       COREDNS-SIGN(7)

NAME
       sign - adds DNSSEC records to zone files.

DESCRIPTION
       The  sign  plugin is used to sign (see RFC 6781)	zones. In this process
       DNSSEC resource records are added. The signatures  that	sign  the  re-
       source  records	sets  have  an expiration date,	this means the signing
       process must be repeated	before this expiration data is reached.	Other-
       wise the	zone's data will go BAD	(RFC 4035, Section 5.5). The sign plu-
       gin takes care of this.

       Only NSEC is supported, sign does not support NSEC3.

       Sign works in conjunction with the file and auto	plugins;  this	plugin
       signs the zones files, auto and file serve the zones data.

       For  this plugin	to work	at least one Common Signing Key, (see coredns-
       keygen(1)) is needed. This key (or keys)	will be	used to	sign  the  en-
       tire  zone. Sign	does not support the ZSK/KSK split, nor	will it	do key
       or algorithm rollovers -	it just	signs.

       Sign will:

       •   (Re)-sign the zone with the CSK(s) when:

	   -   the last	time it	was signed is more than	a  6  days  ago.  Each
	       zone will have some jitter applied to the inception date.

	   -   the signature only has 14 days left before expiring.

       Both these dates	are only checked on the	SOA's signature(s).

       •   Create  RRSIGs  that	 have an inception of -3 hours (minus a	jitter
	   between 0 and 18 hours) and a expiration of +32 (plus a jitter  be-
	   tween 0 and 5 days) days for	every given DNSKEY.

       •   Add	NSEC  records  for all names in	the zone. The TTL for these is
	   the negative	cache TTL from the SOA record.

       •   Add or replace all apex CDS/CDNSKEY records with the	 ones  derived
	   from	the given keys.	For each key two CDS are created one with SHA1
	   and another with SHA256.

       •   Update  the SOA's serial number to the Unix epoch of	when the sign-
	   ing happens.	This will overwrite any	previous serial	number.

       There are two ways that dictate when a zone is signed. Normally every 6
       days (plus jitter) it will be resigned. If for some reason we fail this
       check, the 14 days before expiring kicks	in.

       Keys  are   named   (following	BIND9):	  K<name>+<alg>+<id>.key   and
       K<name>+<alg>+<id>.private.   The  keys	must  not  be included in your
       zone; they will be added	by sign. These	keys  can  be  generated  with
       coredns-keygen  or  BIND9's  dnssec-keygen. You don't have to adhere to
       this naming scheme, but then you	need to	name your keys explicitly, see
       the keys	file directive.

       A generated zone	is written out in a file named db.<name>.signed	in the
       directory  named	 by  the  directory  directive	(which	 defaults   to
       /var/lib/coredns).

SYNTAX
	      sign DBFILE [ZONES...] {
		  key file|directory KEY...|DIR...
		  directory DIR
	      }

       •   DBFILE  the	zone  database	file to	read and parse.	If the path is
	   relative, the path from the root plugin will	be prepended to	it.

       •   ZONES zones it should be sign for. If empty,	 the  zones  from  the
	   configuration block are used.

       •   key	specifies the key(s) (there can	be multiple) to	sign the zone.
	   If file is used the KEY's filenames are used	as is. If directory is
	   used, sign will look	in DIR for K<name>+<alg>+<id> files. Any meta-
	   data	in these files (Activate, Publish,  etc.)  is  ignored.	 These
	   keys	must also be Key Signing Keys (KSK).

       •   directory  specifies	 the  DIR where	CoreDNS	should save zones that
	   have	been signed.  If not given this	defaults to  /var/lib/coredns.
	   The zones are saved under the name db.<name>.signed.	If the path is
	   relative the	path from the root plugin will be prepended to it.

       Keys can	be generated with coredns-keygen, to create one	for use	in the
       sign  plugin,  use: coredns-keygen example.org or dnssec-keygen -a ECD-
       SAP256SHA256 -f KSK example.org.

EXAMPLES
       Sign the	example.org zone contained  in	the  file  db.example.org  and
       write the result	to ./db.example.org.signed to let the file plugin pick
       it  up and serve	it. The	keys used are read from	/etc/coredns/keys/Kex-
       ample.org.key and /etc/coredns/keys/Kexample.org.private.

	      example.org {
		  file db.example.org.signed

		  sign db.example.org {
		      key file /etc/coredns/keys/Kexample.org
		      directory	.
		  }
	      }

       Running this leads to the following log output (note the	timers in this
       example have been set to	shorter	intervals).

	      [WARNING]	plugin/file: Failed to open "open /tmp/db.example.org.signed: no such file or directory": trying again in 1m0s
	      [INFO] plugin/sign: Signing "example.org." because open /tmp/db.example.org.signed: no such file or directory
	      [INFO] plugin/sign: Successfully signed zone "example.org." in "/tmp/db.example.org.signed" with key tags	"59725"	and 1564766865 SOA serial, elapsed 9.357933ms, next: 2019-08-02T22:27:45.270Z
	      [INFO] plugin/file: Successfully reloaded	zone "example.org." in "/tmp/db.example.org.signed" with serial	1564766865

       Or use a	single zone file for multiple zones, note that the  ZONES  are
       repeated	for both plugins.  Also	note this outputs multiple signed out-
       put files. Here we use the default output directory /var/lib/coredns.

	      .	{
		  file /var/lib/coredns/db.example.org.signed example.org
		  file /var/lib/coredns/db.example.net.signed example.net
		  sign db.example.org example.org example.net {
		      key directory /etc/coredns/keys
		  }
	      }

       This  is	 the  same  configuration, but the zones are put in the	server
       block, but note that you	still need to specify what file	is served  for
       what zone in the	file plugin:

	      example.org example.net {
		  file var/lib/coredns/db.example.org.signed example.org
		  file var/lib/coredns/db.example.net.signed example.net
		  sign db.example.org {
		      key directory /etc/coredns/keys
		  }
	      }

       Be careful to fully list	the origins you	want to	sign, if you don't:

	      example.org example.net {
		  sign plugin/sign/testdata/db.example.org miek.org {
		      key file /etc/coredns/keys/Kexample.org
		  }
	      }

       This  will  lead	to db.example.org be signed twice, as this entire sec-
       tion is parsed twice because you	have specified the origins example.org
       and example.net in the server block.

       Forcibly	resigning a zone can be	accomplished by	 removing  the	signed
       zone  file  (CoreDNS  will keep on serving it from memory), and sending
       SIGUSR1 to the process to make it reload	and resign the zone file.

SEE ALSO
       The DNSSEC RFCs:	RFC 4033, RFC 4034  and	 RFC  4035.  And  the  BCP  on
       DNSSEC,	RFC  6781. Further more	the manual pages coredns-keygen(1) and
       dnssec-keygen(8). And the file plugin's documentation.

       Coredns-keygen can be found at https://github.com/coredns/coredns-utils
       <https://github.com/coredns/coredns-utils> in the coredns-keygen	direc-
       tory.

       Other  useful  DNSSEC  tools  can  be  found  in	 ldns  <https://nlnet-
       labs.nl/projects/ldns/about/>,  e.g.   ldns-key2ds to create DS records
       from DNSKEYs.

BUGS
       keys directory is not implemented.

CoreDNS				  March	2021		       COREDNS-SIGN(7)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=coredns-sign&sektion=7&manpath=FreeBSD+Ports+14.3.quarterly>

home | help