mirror of
https://gitlab.isc.org/isc-projects/bind9
synced 2025-08-22 01:59:26 +00:00
382 lines
15 KiB
HTML
382 lines
15 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
<!--
|
||
- Copyright (C) 2000-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">
|
||
<link rel="home" href="Bv9ARM.html" title="BIND 9 Administrator Reference Manual">
|
||
<link rel="up" href="Bv9ARM.ch12.html" title="Manual pages">
|
||
<link rel="prev" href="man.dig.html" title="dig">
|
||
<link rel="next" href="man.dnssec-checkds.html" title="dnssec-checkds">
|
||
</head>
|
||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||
<div class="navheader">
|
||
<table width="100%" summary="Navigation header">
|
||
<tr><th colspan="3" align="center"><span class="application">dnssec-cds</span></th></tr>
|
||
<tr>
|
||
<td width="20%" align="left">
|
||
<a accesskey="p" href="man.dig.html">Prev</a> </td>
|
||
<th width="60%" align="center">Manual pages</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="man.dnssec-checkds.html">Next</a>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
<hr>
|
||
</div>
|
||
<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.13.6.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.13.6.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.13.6.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.13.6.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.13.6.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>
|
||
<div class="navfooter">
|
||
<hr>
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left">
|
||
<a accesskey="p" href="man.dig.html">Prev</a> </td>
|
||
<td width="20%" align="center"><a accesskey="u" href="Bv9ARM.ch12.html">Up</a></td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="man.dnssec-checkds.html">Next</a>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">dig </td>
|
||
<td width="20%" align="center"><a accesskey="h" href="Bv9ARM.html">Home</a></td>
|
||
<td width="40%" align="right" valign="top"> <span class="application">dnssec-checkds</span>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
<p xmlns:db="http://docbook.org/ns/docbook" style="text-align: center;">BIND 9.15.8 (Development Release)</p>
|
||
</body>
|
||
</html>
|