"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.17.5/doc/man/dnssec-cds.1in" (4 Sep 2020, 8512 Bytes) of package /linux/misc/dns/bind9/9.17.5/bind-9.17.5.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "dnssec-cds.1in": 9.17.2_vs_9.17.3.

    1 .\" Man page generated from reStructuredText.
    2 .
    3 .TH "DNSSEC-CDS" "1" "@RELEASE_DATE@" "@PACKAGE_VERSION@" "BIND 9"
    4 .SH NAME
    5 dnssec-cds \- change DS records for a child zone based on CDS/CDNSKEY
    6 .
    7 .nr rst2man-indent-level 0
    8 .
    9 .de1 rstReportMargin
   10 \\$1 \\n[an-margin]
   11 level \\n[rst2man-indent-level]
   12 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
   13 -
   14 \\n[rst2man-indent0]
   15 \\n[rst2man-indent1]
   16 \\n[rst2man-indent2]
   17 ..
   18 .de1 INDENT
   19 .\" .rstReportMargin pre:
   20 . RS \\$1
   21 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
   22 . nr rst2man-indent-level +1
   23 .\" .rstReportMargin post:
   24 ..
   25 .de UNINDENT
   26 . RE
   27 .\" indent \\n[an-margin]
   28 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
   29 .nr rst2man-indent-level -1
   30 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
   31 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
   32 ..
   33 .SH SYNOPSIS
   34 .sp
   35 \fBdnssec\-cds\fP [\fB\-a\fP alg...] [\fB\-c\fP class] [\fB\-D\fP] {\fB\-d\fP dsset\-file} {\fB\-f\fP child\-file} [\fB\-i**[extension]] [\fP\-s** start\-time] [\fB\-T\fP ttl] [\fB\-u\fP] [\fB\-v\fP level] [\fB\-V\fP] {domain}
   36 .SH DESCRIPTION
   37 .sp
   38 The \fBdnssec\-cds\fP command changes DS records at a delegation point
   39 based on CDS or CDNSKEY records published in the child zone. If both CDS
   40 and CDNSKEY records are present in the child zone, the CDS is preferred.
   41 This enables a child zone to inform its parent of upcoming changes to
   42 its key\-signing keys (KSKs); by polling periodically with \fBdnssec\-cds\fP, the
   43 parent can keep the DS records up\-to\-date and enable automatic rolling
   44 of KSKs.
   45 .sp
   46 Two input files are required. The \fB\-f child\-file\fP option specifies a
   47 file containing the child\(aqs CDS and/or CDNSKEY records, plus RRSIG and
   48 DNSKEY records so that they can be authenticated. The \fB\-d path\fP option
   49 specifies the location of a file containing the current DS records. For
   50 example, this could be a \fBdsset\-\fP file generated by
   51 \fBdnssec\-signzone\fP, or the output of \fBdnssec\-dsfromkey\fP, or the
   52 output of a previous run of \fBdnssec\-cds\fP\&.
   53 .sp
   54 The \fBdnssec\-cds\fP command uses special DNSSEC validation logic
   55 specified by \fI\%RFC 7344\fP\&. It requires that the CDS and/or CDNSKEY records
   56 be validly signed by a key represented in the existing DS records. This
   57 is typically the pre\-existing KSK.
   58 .sp
   59 For protection against replay attacks, the signatures on the child
   60 records must not be older than they were on a previous run of
   61 \fBdnssec\-cds\fP\&. Their age is obtained from the modification time of the
   62 \fBdsset\-\fP file, or from the \fB\-s\fP option.
   63 .sp
   64 To protect against breaking the delegation, \fBdnssec\-cds\fP ensures that
   65 the DNSKEY RRset can be verified by every key algorithm in the new DS
   66 RRset, and that the same set of keys are covered by every DS digest
   67 type.
   68 .sp
   69 By default, replacement DS records are written to the standard output;
   70 with the \fB\-i\fP option the input file is overwritten in place. The
   71 replacement DS records are the same as the existing records, when no
   72 change is required. The output can be empty if the CDS/CDNSKEY records
   73 specify that the child zone wants to be insecure.
   74 .sp
   75 \fBWARNING:\fP
   76 .INDENT 0.0
   77 .INDENT 3.5
   78 Be careful not to delete the DS records when \fBdnssec\-cds\fP fails!
   79 .UNINDENT
   80 .UNINDENT
   81 .sp
   82 Alternatively, \fBdnssec\-cds \-u\fP writes an \fBnsupdate\fP script to the
   83 standard output. The \fB\-u\fP and \fB\-i\fP options can be used together to
   84 maintain a \fBdsset\-\fP file as well as emit an \fBnsupdate\fP script.
   85 .SH OPTIONS
   86 .INDENT 0.0
   87 .TP
   88 .B \fB\-a algorithm\fP
   89 This option specifies a digest algorithm to use when converting CDNSKEY records to
   90 DS records. This option can be repeated, so that multiple DS records
   91 are created for each CDNSKEY record. This option has no effect when
   92 using CDS records.
   93 .sp
   94 The algorithm must be one of SHA\-1, SHA\-256, or SHA\-384. These values
   95 are case\-insensitive, and the hyphen may be omitted. If no algorithm
   96 is specified, the default is SHA\-256.
   97 .TP
   98 .B \fB\-c class\fP
   99 This option specifies the DNS class of the zones.
  100 .TP
  101 .B \fB\-D\fP
  102 This option generates DS records from CDNSKEY records if both CDS and CDNSKEY
  103 records are present in the child zone. By default CDS records are
  104 preferred.
  105 .TP
  106 .B \fB\-d path\fP
  107 This specifies the location of the parent DS records. The path can be the name of a file
  108 containing the DS records; if it is a directory, \fBdnssec\-cds\fP
  109 looks for a \fBdsset\-\fP file for the domain inside the directory.
  110 .sp
  111 To protect against replay attacks, child records are rejected if they
  112 were signed earlier than the modification time of the \fBdsset\-\fP
  113 file. This can be adjusted with the \fB\-s\fP option.
  114 .TP
  115 .B \fB\-f child\-file\fP
  116 This option specifies the file containing the child\(aqs CDS and/or CDNSKEY records, plus its
  117 DNSKEY records and the covering RRSIG records, so that they can be
  118 authenticated.
  119 .sp
  120 The examples below describe how to generate this file.
  121 .TP
  122 .B \fB\-iextension\fP
  123 This option updates the \fBdsset\-\fP file in place, instead of writing DS records to
  124 the standard output.
  125 .sp
  126 There must be no space between the \fB\-i\fP and the extension. If
  127 no extension is provided, the old \fBdsset\-\fP is discarded. If an
  128 extension is present, a backup of the old \fBdsset\-\fP file is kept
  129 with the extension appended to its filename.
  130 .sp
  131 To protect against replay attacks, the modification time of the
  132 \fBdsset\-\fP file is set to match the signature inception time of the
  133 child records, provided that it is later than the file\(aqs current
  134 modification time.
  135 .TP
  136 .B \fB\-s start\-time\fP
  137 This option specifies the date and time after which RRSIG records become
  138 acceptable. This can be either an absolute or a relative time. An
  139 absolute start time is indicated by a number in YYYYMMDDHHMMSS
  140 notation; 20170827133700 denotes 13:37:00 UTC on August 27th, 2017. A
  141 time relative to the \fBdsset\-\fP file is indicated with \fB\-N\fP, which is N
  142 seconds before the file modification time. A time relative to the
  143 current time is indicated with \fBnow+N\fP\&.
  144 .sp
  145 If no start\-time is specified, the modification time of the
  146 \fBdsset\-\fP file is used.
  147 .TP
  148 .B \fB\-T ttl\fP
  149 This option specifies a TTL to be used for new DS records. If not specified, the
  150 default is the TTL of the old DS records. If they had no explicit TTL,
  151 the new DS records also have no explicit TTL.
  152 .TP
  153 .B \fB\-u\fP
  154 This option writes an \fBnsupdate\fP script to the standard output, instead of
  155 printing the new DS reords. The output is empty if no change is
  156 needed.
  157 .sp
  158 Note: The TTL of new records needs to be specified: it can be done in the
  159 original \fBdsset\-\fP file, with the \fB\-T\fP option, or using the
  160 \fBnsupdate\fP \fBttl\fP command.
  161 .TP
  162 .B \fB\-V\fP
  163 This option prints version information.
  164 .TP
  165 .B \fB\-v level\fP
  166 This option sets the debugging level. Level 1 is intended to be usefully verbose
  167 for general users; higher levels are intended for developers.
  168 .TP
  169 .B \fBdomain\fP
  170 This indicates the name of the delegation point/child zone apex.
  171 .UNINDENT
  172 .SH EXIT STATUS
  173 .sp
  174 The \fBdnssec\-cds\fP command exits 0 on success, or non\-zero if an error
  175 occurred.
  176 .sp
  177 If successful, the DS records may or may not need to be
  178 changed.
  179 .SH EXAMPLES
  180 .sp
  181 Before running \fBdnssec\-signzone\fP, ensure that the delegations
  182 are up\-to\-date by running \fBdnssec\-cds\fP on every \fBdsset\-\fP file.
  183 .sp
  184 To fetch the child records required by \fBdnssec\-cds\fP, invoke
  185 \fBdig\fP as in the script below. It is acceptable if the \fBdig\fP fails, since
  186 \fBdnssec\-cds\fP performs all the necessary checking.
  187 .INDENT 0.0
  188 .INDENT 3.5
  189 .sp
  190 .nf
  191 .ft C
  192 for f in dsset\-*
  193 do
  194     d=${f#dsset\-}
  195     dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
  196     dnssec\-cds \-i \-f /dev/stdin \-d $f $d
  197 done
  198 .ft P
  199 .fi
  200 .UNINDENT
  201 .UNINDENT
  202 .sp
  203 When the parent zone is automatically signed by \fBnamed\fP,
  204 \fBdnssec\-cds\fP can be used with \fBnsupdate\fP to maintain a delegation as follows.
  205 The \fBdsset\-\fP file allows the script to avoid having to fetch and
  206 validate the parent DS records, and it maintains the replay attack
  207 protection time.
  208 .INDENT 0.0
  209 .INDENT 3.5
  210 .sp
  211 .nf
  212 .ft C
  213 dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
  214 dnssec\-cds \-u \-i \-f /dev/stdin \-d $f $d |
  215 nsupdate \-l
  216 .ft P
  217 .fi
  218 .UNINDENT
  219 .UNINDENT
  220 .SH SEE ALSO
  221 .sp
  222 \fBdig(1)\fP, \fBdnssec\-settime(8)\fP, \fBdnssec\-signzone(8)\fP, \fBnsupdate(1)\fP, BIND 9 Administrator
  223 Reference Manual, \fI\%RFC 7344\fP\&.
  224 .SH AUTHOR
  225 Internet Systems Consortium
  226 .SH COPYRIGHT
  227 2020, Internet Systems Consortium
  228 .\" Generated by docutils manpage writer.
  229 .