237 lines
7.6 KiB
Groff
237 lines
7.6 KiB
Groff
.\" Generated by Mmark Markdown Processer - mmark.miek.nl
|
|
.TH "COREDNS-SIGN" 7 "March 2021" "CoreDNS" "CoreDNS Plugins"
|
|
|
|
.SH "NAME"
|
|
.PP
|
|
\fIsign\fP - adds 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 to the zone. 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.
|
|
|
|
.PP
|
|
Only NSEC is supported, \fIsign\fP does \fInot\fP 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 \fInot\fP 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). This concerns the DNSSEC data, the
|
|
\fIsign\fP plugin will also take into account and resign if:
|
|
|
|
.RS
|
|
.IP \(en 4
|
|
the \fBmtime\fP of the zone file has changed, since the last time it was checked.
|
|
.IP \(en 4
|
|
the signed zone file doesn't exist on disk.
|
|
|
|
.RE
|
|
.IP \(bu 4
|
|
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 between 0 and 5 days) days for every given DNSKEY.
|
|
.IP \(bu 4
|
|
Add NSEC records for all names in the zone. The TTL for these is the negative cache TTL from the
|
|
SOA record.
|
|
.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
|
|
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 plugin 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 plugin 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 "SEE ALSO"
|
|
.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.
|
|
|
|
.PP
|
|
Other useful DNSSEC tools can be found in ldns
|
|
\[la]https://nlnetlabs.nl/projects/ldns/about/\[ra], e.g.
|
|
\fB\fCldns-key2ds\fR to create DS records from DNSKEYs.
|
|
|
|
.SH "BUGS"
|
|
.PP
|
|
\fB\fCkeys directory\fR is not implemented.
|
|
|