<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--
- Copyright (C) 2017, 2018 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 typicially 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
(SHA1), SHA-256 (SHA256), GOST, or SHA-384 (SHA384). These
values are case insensitive. 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>
![[BACK]](/icons/back.gif){kind=icon}
Return to dnssec-cds.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / external / mpl / bind / dist / bin / dnssec