diff options
Diffstat (limited to 'man/coredns-sign.7')
| -rw-r--r-- | man/coredns-sign.7 | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/man/coredns-sign.7 b/man/coredns-sign.7 new file mode 100644 index 000000000..773e930ab --- /dev/null +++ b/man/coredns-sign.7 @@ -0,0 +1,220 @@ +.\" Generated by Mmark Markdown Processer - mmark.miek.nl +.TH "COREDNS-SIGN" 7 "August 2019" "CoreDNS" "CoreDNS Plugins" + +.SH "NAME" +.PP +\fIsign\fP - add DNSSEC records to zone files. + +.SH "DESCRIPTION" +.PP +The \fIsign\fP plugin is used to sign (see RFC 6781) zones. In this process DNSSEC resource records are +added. The signatures that sign the resource records sets have an expiration date, this means the +signing process must be repeated before this expiration data is reached. Otherwise the zone's data +will go BAD (RFC 4035, Section 5.5). The \fIsign\fP plugin takes care of this. \fISign\fP works, but has +a couple of limitations, see the "Bugs" section. + +.PP +Only NSEC is supported, \fIsign\fP does not support NSEC3. + +.PP +\fISign\fP works in conjunction with the \fIfile\fP and \fIauto\fP plugins; this plugin \fBsigns\fP the zones +files, \fIauto\fP and \fIfile\fP \fBserve\fP the zones \fIdata\fP. + +.PP +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 entire zone. \fISign\fP does not support the ZSK/KSK split, nor will +it do key or algorithm rollovers - it just signs. + +.PP +\fISign\fP will: + +.IP \(bu 4 +(Re)-sign the zone with the CSK(s) when: + +.RS +.IP \(en 4 +the last time it was signed is more than a 6 days ago. Each zone will have some jitter +applied to the inception date. +.IP \(en 4 +the signature only has 14 days left before expiring. + +.RE + + +Both these dates are only checked on the SOA's signature(s). +.IP \(bu 4 +Create signatures that have an inception of -3 hours (minus a jitter between 0 and 18 hours) +and a expiration of +32 days for every given DNSKEY. +.IP \(bu 4 +Add or replace \fIall\fP 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. +.IP \(bu 4 +Update the SOA's serial number to the \fIUnix epoch\fP of when the signing happens. This will +overwrite \fIany\fP previous serial number. + + +.PP +Thus 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. + +.PP +Keys are named (following BIND9): \fB\fCK<name>+<alg>+<id>.key\fR and \fB\fCK<name>+<alg>+<id>.private\fR. +The keys \fBmust not\fP be included in your zone; they will be added by \fIsign\fP. These keys can be +generated with \fB\fCcoredns-keygen\fR or BIND9's \fB\fCdnssec-keygen\fR. You don't have to adhere to this naming +scheme, but then you need to name your keys explicitly, see the \fB\fCkeys file\fR directive. + +.PP +A generated zone is written out in a file named \fB\fCdb.<name>.signed\fR in the directory named by the +\fB\fCdirectory\fR directive (which defaults to \fB\fC/var/lib/coredns\fR). + +.SH "SYNTAX" +.PP +.RS + +.nf +sign DBFILE [ZONES...] { + key file|directory KEY...|DIR... + directory DIR +} + +.fi +.RE + +.IP \(bu 4 +\fBDBFILE\fP the zone database file to read and parse. If the path is relative, the path from the +\fIroot\fP directive will be prepended to it. +.IP \(bu 4 +\fBZONES\fP zones it should be sign for. If empty, the zones from the configuration block are +used. +.IP \(bu 4 +\fB\fCkey\fR specifies the key(s) (there can be multiple) to sign the zone. If \fB\fCfile\fR is +used the \fBKEY\fP's filenames are used as is. If \fB\fCdirectory\fR is used, \fIsign\fP will look in \fBDIR\fP +for \fB\fCK<name>+<alg>+<id>\fR files. Any metadata in these files (Activate, Publish, etc.) is +\fIignored\fP. These keys must also be Key Signing Keys (KSK). +.IP \(bu 4 +\fB\fCdirectory\fR specifies the \fBDIR\fP where CoreDNS should save zones that have been signed. +If not given this defaults to \fB\fC/var/lib/coredns\fR. The zones are saved under the name +\fB\fCdb.<name>.signed\fR. If the path is relative the path from the \fIroot\fP directive will be prepended +to it. + + +.PP +Keys can be generated with \fB\fCcoredns-keygen\fR, to create one for use in the \fIsign\fP plugin, use: +\fB\fCcoredns-keygen example.org\fR or \fB\fCdnssec-keygen -a ECDSAP256SHA256 -f KSK example.org\fR. + +.SH "EXAMPLES" +.PP +Sign the \fB\fCexample.org\fR zone contained in the file \fB\fCdb.example.org\fR and write the result to +\fB\fC./db.example.org.signed\fR to let the \fIfile\fP plugin pick it up and serve it. The keys used +are read from \fB\fC/etc/coredns/keys/Kexample.org.key\fR and \fB\fC/etc/coredns/keys/Kexample.org.private\fR. + +.PP +.RS + +.nf +example.org { + file db.example.org.signed + + sign db.example.org { + key file /etc/coredns/keys/Kexample.org + directory . + } +} + +.fi +.RE + +.PP +Running this leads to the following log output (note the timers in this example have been set to +shorter intervals). + +.PP +.RS + +.nf +[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 + +.fi +.RE + +.PP +Or use a single zone file for \fImultiple\fP zones, note that the \fBZONES\fP are repeated for both plugins. +Also note this outputs \fImultiple\fP signed output files. Here we use the default output directory +\fB\fC/var/lib/coredns\fR. + +.PP +.RS + +.nf +\&. { + 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 + } +} + +.fi +.RE + +.PP +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 \fIfile\fP plugin: + +.PP +.RS + +.nf +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 + } +} + +.fi +.RE + +.PP +Be careful to fully list the origins you want to sign, if you don't: + +.PP +.RS + +.nf +example.org example.net { + sign plugin/sign/testdata/db.example.org miek.org { + key file /etc/coredns/keys/Kexample.org + } +} + +.fi +.RE + +.PP +This will lead to \fB\fCdb.example.org\fR be signed \fItwice\fP, as this entire section is parsed twice because +you have specified the origins \fB\fCexample.org\fR and \fB\fCexample.net\fR in the server block. + +.PP +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. + +.SH "ALSO SEE" +.PP +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 \fIfile\fP plugin's documentation. + +.PP +Coredns-keygen can be found at https://github.com/coredns/coredns-utils +\[la]https://github.com/coredns/coredns-utils\[ra] in the coredns-keygen directory. + +.SH "BUGS" +.PP +\fB\fCkeys directory\fR is not implemented. Glue records are currently signed, and no DS records are added +for child zones. + |