mirror of
https://gitlab.isc.org/isc-projects/bind9.git
synced 2025-04-18 09:44:09 +03:00
344 lines
14 KiB
HTML
344 lines
14 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<!--
|
|
- Copyright (C) 2017-2020 Internet Systems Consortium, Inc. ("ISC")
|
|
-
|
|
- This Source Code Form is subject to the terms of the Mozilla Public
|
|
- License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
- file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
-->
|
|
<html lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|
<title>dnssec-cds</title>
|
|
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
|
</head>
|
|
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry">
|
|
<a name="man.dnssec-cds"></a><div class="titlepage"></div>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="refnamediv">
|
|
<h2>Name</h2>
|
|
<p>
|
|
<span class="application">dnssec-cds</span>
|
|
— change DS records for a child zone based on CDS/CDNSKEY
|
|
</p>
|
|
</div>
|
|
|
|
|
|
|
|
<div class="refsynopsisdiv">
|
|
<h2>Synopsis</h2>
|
|
<div class="cmdsynopsis"><p>
|
|
<code class="command">dnssec-cds</code>
|
|
[<code class="option">-a <em class="replaceable"><code>alg</code></em></code>...]
|
|
[<code class="option">-c <em class="replaceable"><code>class</code></em></code>]
|
|
[<code class="option">-D</code>]
|
|
{<code class="option">-d <em class="replaceable"><code>dsset-file</code></em></code>}
|
|
{<code class="option">-f <em class="replaceable"><code>child-file</code></em></code>}
|
|
[<code class="option">-i</code> [<em class="replaceable"><code>extension</code></em>]]
|
|
[<code class="option">-s <em class="replaceable"><code>start-time</code></em></code>]
|
|
[<code class="option">-T <em class="replaceable"><code>ttl</code></em></code>]
|
|
[<code class="option">-u</code>]
|
|
[<code class="option">-v <em class="replaceable"><code>level</code></em></code>]
|
|
[<code class="option">-V</code>]
|
|
{domain}
|
|
</p></div>
|
|
</div>
|
|
|
|
<div class="refsection">
|
|
<a name="id-1.7"></a><h2>DESCRIPTION</h2>
|
|
|
|
<p>
|
|
The <span class="command"><strong>dnssec-cds</strong></span> command changes DS records at
|
|
a delegation point based on CDS or CDNSKEY records published in
|
|
the child zone. If both CDS and CDNSKEY records are present in
|
|
the child zone, the CDS is preferred. This enables a child zone
|
|
to inform its parent of upcoming changes to its key-signing keys;
|
|
by polling periodically with <span class="command"><strong>dnssec-cds</strong></span>, the
|
|
parent can keep the DS records up to date and enable automatic
|
|
rolling of KSKs.
|
|
</p>
|
|
<p>
|
|
Two input files are required. The
|
|
<code class="option">-f <em class="replaceable"><code>child-file</code></em></code>
|
|
option specifies a file containing the child's CDS and/or CDNSKEY
|
|
records, plus RRSIG and DNSKEY records so that they can be
|
|
authenticated. The
|
|
<code class="option">-d <em class="replaceable"><code>path</code></em></code>
|
|
option specifies the location of a file containing the current DS
|
|
records. For example, this could be a <code class="filename">dsset-</code>
|
|
file generated by <span class="command"><strong>dnssec-signzone</strong></span>, or the output of
|
|
<span class="command"><strong>dnssec-dsfromkey</strong></span>, or the output of a previous
|
|
run of <span class="command"><strong>dnssec-cds</strong></span>.
|
|
</p>
|
|
<p>
|
|
The <span class="command"><strong>dnssec-cds</strong></span> command uses special DNSSEC
|
|
validation logic specified by RFC 7344. It requires that the CDS
|
|
and/or CDNSKEY records are validly signed by a key represented in the
|
|
existing DS records. This will typically be the pre-existing
|
|
key-signing key (KSK).
|
|
</p>
|
|
<p>
|
|
For protection against replay attacks, the signatures on the
|
|
child records must not be older than they were on a previous run
|
|
of <span class="command"><strong>dnssec-cds</strong></span>. This time is obtained from the
|
|
modification time of the <code class="filename">dsset-</code> file, or
|
|
from the <code class="option">-s</code> option.
|
|
</p>
|
|
<p>
|
|
To protect against breaking the delegation,
|
|
<span class="command"><strong>dnssec-cds</strong></span> ensures that the DNSKEY RRset can be
|
|
verified by every key algorithm in the new DS RRset, and that the
|
|
same set of keys are covered by every DS digest type.
|
|
</p>
|
|
<p>
|
|
By default, replacement DS records are written to the standard
|
|
output; with the <code class="option">-i</code> option the input file is
|
|
overwritten in place. The replacement DS records will be the
|
|
same as the existing records when no change is required. The
|
|
output can be empty if the CDS / CDNSKEY records specify that
|
|
the child zone wants to go insecure.
|
|
</p>
|
|
<p>
|
|
Warning: Be careful not to delete the DS records
|
|
when <span class="command"><strong>dnssec-cds</strong></span> fails!
|
|
</p>
|
|
<p>
|
|
Alternatively, <span class="command"><strong>dnssec-cds -u</strong></span> writes
|
|
an <span class="command"><strong>nsupdate</strong></span> script to the standard output.
|
|
You can use the <code class="option">-u</code> and <code class="option">-i</code>
|
|
options together to maintain a <code class="filename">dsset-</code> file
|
|
as well as emit an <span class="command"><strong>nsupdate</strong></span> script.
|
|
</p>
|
|
|
|
</div>
|
|
|
|
<div class="refsection">
|
|
<a name="id-1.8"></a><h2>OPTIONS</h2>
|
|
|
|
<div class="variablelist"><dl class="variablelist">
|
|
<dt><span class="term">-a <em class="replaceable"><code>algorithm</code></em></span></dt>
|
|
<dd>
|
|
<p>
|
|
Specify a digest algorithm to use when converting CDNSKEY
|
|
records to DS records. This option can be repeated, so
|
|
that multiple DS records are created for each CDNSKEY
|
|
record. This option has no effect when using CDS records.
|
|
</p>
|
|
<p>
|
|
The <em class="replaceable"><code>algorithm</code></em> must be one of
|
|
SHA-1, SHA-256, or SHA-384. These values are case insensitive,
|
|
and the hyphen may be omitted. If no algorithm is specified,
|
|
the default is SHA-256.
|
|
</p>
|
|
</dd>
|
|
<dt><span class="term">-c <em class="replaceable"><code>class</code></em></span></dt>
|
|
<dd>
|
|
<p>
|
|
Specifies the DNS class of the zones.
|
|
</p>
|
|
</dd>
|
|
<dt><span class="term">-D</span></dt>
|
|
<dd>
|
|
<p>
|
|
Generate DS records from CDNSKEY records if both CDS and
|
|
CDNSKEY records are present in the child zone. By default
|
|
CDS records are preferred.
|
|
</p>
|
|
</dd>
|
|
<dt><span class="term">-d <em class="replaceable"><code>path</code></em></span></dt>
|
|
<dd>
|
|
<p>
|
|
Location of the parent DS records.
|
|
The <em class="replaceable"><code>path</code></em> can be the name of a file
|
|
containing the DS records, or if it is a
|
|
directory, <span class="command"><strong>dnssec-cds</strong></span> looks for
|
|
a <code class="filename">dsset-</code> file for
|
|
the <em class="replaceable"><code>domain</code></em> inside the directory.
|
|
</p>
|
|
<p>
|
|
To protect against replay attacks, child records are
|
|
rejected if they were signed earlier than the modification
|
|
time of the <code class="filename">dsset-</code> file. This can be
|
|
adjusted with the <code class="option">-s</code> option.
|
|
</p>
|
|
</dd>
|
|
<dt><span class="term">-f <em class="replaceable"><code>child-file</code></em></span></dt>
|
|
<dd>
|
|
<p>
|
|
File containing the child's CDS and/or CDNSKEY records,
|
|
plus its DNSKEY records and the covering RRSIG records so
|
|
that they can be authenticated.
|
|
</p>
|
|
<p>
|
|
The EXAMPLES below describe how to generate this file.
|
|
</p>
|
|
</dd>
|
|
<dt><span class="term">-i[<em class="replaceable"><code>extension</code></em>]</span></dt>
|
|
<dd>
|
|
<p>
|
|
Update the <code class="filename">dsset-</code> file in place,
|
|
instead of writing DS records to the standard output.
|
|
</p>
|
|
<p>
|
|
There must be no space between the <code class="option">-i</code> and
|
|
the <em class="replaceable"><code>extension</code></em>. If you provide
|
|
no <em class="replaceable"><code>extension</code></em> then the
|
|
old <code class="filename">dsset-</code> is discarded. If
|
|
an <em class="replaceable"><code>extension</code></em> is present, a
|
|
backup of the old <code class="filename">dsset-</code> file is kept
|
|
with the <em class="replaceable"><code>extension</code></em> appended to
|
|
its filename.
|
|
</p>
|
|
<p>
|
|
To protect against replay attacks, the modification time
|
|
of the <code class="filename">dsset-</code> file is set to match
|
|
the signature inception time of the child records,
|
|
provided that is later than the file's current
|
|
modification time.
|
|
</p>
|
|
</dd>
|
|
<dt><span class="term">-s <em class="replaceable"><code>start-time</code></em></span></dt>
|
|
<dd>
|
|
<p>
|
|
Specify the date and time after which RRSIG records become
|
|
acceptable. This can be either an absolute or relative
|
|
time. An absolute start time is indicated by a number in
|
|
YYYYMMDDHHMMSS notation; 20170827133700 denotes 13:37:00
|
|
UTC on August 27th, 2017. A time relative to
|
|
the <code class="filename">dsset-</code> file is indicated with -N,
|
|
which is N seconds before the file modification time. A
|
|
time relative to the current time is indicated with now+N.
|
|
</p>
|
|
<p>
|
|
If no <em class="replaceable"><code>start-time</code></em> is specified, the
|
|
modification time of the <code class="filename">dsset-</code> file
|
|
is used.
|
|
</p>
|
|
</dd>
|
|
<dt><span class="term">-T <em class="replaceable"><code>ttl</code></em></span></dt>
|
|
<dd>
|
|
<p>
|
|
Specifies a TTL to be used for new DS records. If not
|
|
specified, the default is the TTL of the old DS records.
|
|
If they had no explicit TTL then the new DS records also
|
|
have no explicit TTL.
|
|
</p>
|
|
</dd>
|
|
<dt><span class="term">-u</span></dt>
|
|
<dd>
|
|
<p>
|
|
Write an <span class="command"><strong>nsupdate</strong></span> script to the
|
|
standard output, instead of printing the new DS reords.
|
|
The output will be empty if no change is needed.
|
|
</p>
|
|
<p>
|
|
Note: The TTL of new records needs to be specified, either
|
|
in the original <code class="filename">dsset-</code> file, or with
|
|
the <code class="option">-T</code> option, or using
|
|
the <span class="command"><strong>nsupdate</strong></span> <span class="command"><strong>ttl</strong></span>
|
|
command.
|
|
</p>
|
|
</dd>
|
|
<dt><span class="term">-V</span></dt>
|
|
<dd>
|
|
<p>
|
|
Print version information.
|
|
</p>
|
|
</dd>
|
|
<dt><span class="term">-v <em class="replaceable"><code>level</code></em></span></dt>
|
|
<dd>
|
|
<p>
|
|
Sets the debugging level. Level 1 is intended to be
|
|
usefully verbose for general users; higher levels are
|
|
intended for developers.
|
|
</p>
|
|
</dd>
|
|
<dt><span class="term"><em class="replaceable"><code>domain</code></em></span></dt>
|
|
<dd>
|
|
<p>
|
|
The name of the delegation point / child zone apex.
|
|
</p>
|
|
</dd>
|
|
</dl></div>
|
|
</div>
|
|
|
|
<div class="refsection">
|
|
<a name="id-1.9"></a><h2>EXIT STATUS</h2>
|
|
|
|
<p>
|
|
The <span class="command"><strong>dnssec-cds</strong></span> command exits 0 on success, or
|
|
non-zero if an error occurred.
|
|
</p>
|
|
<p>
|
|
In the success case, the DS records might or might not need
|
|
to be changed.
|
|
</p>
|
|
|
|
</div>
|
|
|
|
<div class="refsection">
|
|
<a name="id-1.10"></a><h2>EXAMPLES</h2>
|
|
|
|
<p>
|
|
Before running <span class="command"><strong>dnssec-signzone</strong></span>, you can ensure
|
|
that the delegations are up-to-date by running
|
|
<span class="command"><strong>dnssec-cds</strong></span> on every <code class="filename">dsset-</code> file.
|
|
</p>
|
|
<p>
|
|
To fetch the child records required by <span class="command"><strong>dnssec-cds</strong></span>
|
|
you can invoke <span class="command"><strong>dig</strong></span> as in the script below. It's
|
|
okay if the <span class="command"><strong>dig</strong></span> fails since
|
|
<span class="command"><strong>dnssec-cds</strong></span> performs all the necessary checking.
|
|
</p>
|
|
<pre class="programlisting">for f in dsset-*
|
|
do
|
|
d=${f#dsset-}
|
|
dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
|
|
dnssec-cds -i -f /dev/stdin -d $f $d
|
|
done
|
|
</pre>
|
|
|
|
<p>
|
|
When the parent zone is automatically signed by
|
|
<span class="command"><strong>named</strong></span>, you can use <span class="command"><strong>dnssec-cds</strong></span>
|
|
with <span class="command"><strong>nsupdate</strong></span> to maintain a delegation as follows.
|
|
The <code class="filename">dsset-</code> file allows the script to avoid
|
|
having to fetch and validate the parent DS records, and it keeps the
|
|
replay attack protection time.
|
|
</p>
|
|
<pre class="programlisting">
|
|
dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
|
|
dnssec-cds -u -i -f /dev/stdin -d $f $d |
|
|
nsupdate -l
|
|
</pre>
|
|
</div>
|
|
|
|
<div class="refsection">
|
|
<a name="id-1.11"></a><h2>SEE ALSO</h2>
|
|
|
|
<p>
|
|
<span class="citerefentry">
|
|
<span class="refentrytitle">dig</span>(1)
|
|
</span>,
|
|
<span class="citerefentry">
|
|
<span class="refentrytitle">dnssec-settime</span>(8)
|
|
</span>,
|
|
<span class="citerefentry">
|
|
<span class="refentrytitle">dnssec-signzone</span>(8)
|
|
</span>,
|
|
<span class="citerefentry">
|
|
<span class="refentrytitle">nsupdate</span>(1)
|
|
</span>,
|
|
<em class="citetitle">BIND 9 Administrator Reference Manual</em>,
|
|
<em class="citetitle">RFC 7344</em>.
|
|
</p>
|
|
|
|
</div>
|
|
|
|
</div></body>
|
|
</html>
|