1 .. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2 .. 3 .. SPDX-License-Identifier: MPL-2.0 4 .. 5 .. This Source Code Form is subject to the terms of the Mozilla Public 6 .. License, v. 2.0. If a copy of the MPL was not distributed with this 7 .. file, you can obtain one at https://mozilla.org/MPL/2.0/. 8 .. 9 .. See the COPYRIGHT file distributed with this work for additional 10 .. information regarding copyright ownership. 11 12 .. highlight: console 13 14 .. iscman:: dnssec-cds 15 .. program:: dnssec-cds 16 .. _man_dnssec-cds: 17 18 dnssec-cds - change DS records for a child zone based on CDS/CDNSKEY 19 -------------------------------------------------------------------- 20 21 Synopsis 22 ~~~~~~~~ 23 24 :program:`dnssec-cds` [**-a** alg...] [**-c** class] [**-D**] {**-d** dsset-file} {**-f** child-file} [**-i**[extension]] [**-s** start-time] [**-T** ttl] [**-u**] [**-v** level] [**-V**] {domain} 25 26 Description 27 ~~~~~~~~~~~ 28 29 The :program:`dnssec-cds` command changes DS records at a delegation point 30 based on CDS or CDNSKEY records published in the child zone. If both CDS 31 and CDNSKEY records are present in the child zone, the CDS is preferred. 32 This enables a child zone to inform its parent of upcoming changes to 33 its key-signing keys (KSKs); by polling periodically with :program:`dnssec-cds`, the 34 parent can keep the DS records up-to-date and enable automatic rolling 35 of KSKs. 36 37 Two input files are required. The :option:`-f child-file <-f>` option specifies a 38 file containing the child's CDS and/or CDNSKEY records, plus RRSIG and 39 DNSKEY records so that they can be authenticated. The :option:`-d path <-d>` option 40 specifies the location of a file containing the current DS records. For 41 example, this could be a ``dsset-`` file generated by 42 :iscman:`dnssec-signzone`, or the output of :iscman:`dnssec-dsfromkey`, or the 43 output of a previous run of :program:`dnssec-cds`. 44 45 The :program:`dnssec-cds` command uses special DNSSEC validation logic 46 specified by :rfc:`7344`. It requires that the CDS and/or CDNSKEY records 47 be validly signed by a key represented in the existing DS records. This 48 is typically the pre-existing KSK. 49 50 For protection against replay attacks, the signatures on the child 51 records must not be older than they were on a previous run of 52 :program:`dnssec-cds`. Their age is obtained from the modification time of the 53 ``dsset-`` file, or from the :option:`-s` option. 54 55 To protect against breaking the delegation, :program:`dnssec-cds` ensures that 56 the DNSKEY RRset can be verified by every key algorithm in the new DS 57 RRset, and that the same set of keys are covered by every DS digest 58 type. 59 60 By default, replacement DS records are written to the standard output; 61 with the :option:`-i` option the input file is overwritten in place. The 62 replacement DS records are the same as the existing records, when no 63 change is required. The output can be empty if the CDS/CDNSKEY records 64 specify that the child zone wants to be insecure. 65 66 .. warning:: 67 68 Be careful not to delete the DS records when :program:`dnssec-cds` fails! 69 70 Alternatively, :option`dnssec-cds -u` writes an :iscman:`nsupdate` script to the 71 standard output. The :option:`-u` and :option:`-i` options can be used together to 72 maintain a ``dsset-`` file as well as emit an :iscman:`nsupdate` script. 73 74 Options 75 ~~~~~~~ 76 77 .. option:: -a algorithm 78 79 When converting CDS records to DS records, this option specifies 80 the acceptable digest algorithms. This option can be repeated, so 81 that multiple digest types are allowed. If none of the CDS records 82 use an acceptable digest type, :program:`dnssec-cds` will try to use CDNSKEY 83 records instead; if there are no CDNSKEY records, it reports an error. 84 85 When converting CDNSKEY records to DS records, this option specifies the 86 digest algorithm to use. It can be repeated, so that multiple DS records 87 are created for each CDNSKEY records. 88 89 The algorithm must be one of SHA-1, SHA-256, or SHA-384. These values 90 are case-insensitive, and the hyphen may be omitted. If no algorithm 91 is specified, the default is SHA-256 only. 92 93 .. option:: -c class 94 95 This option specifies the DNS class of the zones. 96 97 .. option:: -D 98 99 This option generates DS records from CDNSKEY records if both CDS and CDNSKEY 100 records are present in the child zone. By default CDS records are 101 preferred. 102 103 .. option:: -d path 104 105 This specifies the location of the parent DS records. The path can be the name of a file 106 containing the DS records; if it is a directory, :program:`dnssec-cds` 107 looks for a ``dsset-`` file for the domain inside the directory. 108 109 To protect against replay attacks, child records are rejected if they 110 were signed earlier than the modification time of the ``dsset-`` 111 file. This can be adjusted with the :option:`-s` option. 112 113 .. option:: -f child-file 114 115 This option specifies the file containing the child's CDS and/or CDNSKEY records, plus its 116 DNSKEY records and the covering RRSIG records, so that they can be 117 authenticated. 118 119 The examples below describe how to generate this file. 120 121 .. option:: -i extension 122 123 This option updates the ``dsset-`` file in place, instead of writing DS records to 124 the standard output. 125 126 There must be no space between the :option:`-i` and the extension. If 127 no extension is provided, the old ``dsset-`` is discarded. If an 128 extension is present, a backup of the old ``dsset-`` file is kept 129 with the extension appended to its filename. 130 131 To protect against replay attacks, the modification time of the 132 ``dsset-`` file is set to match the signature inception time of the 133 child records, provided that it is later than the file's current 134 modification time. 135 136 .. option:: -s start-time 137 138 This option specifies the date and time after which RRSIG records become 139 acceptable. This can be either an absolute or a relative time. An 140 absolute start time is indicated by a number in YYYYMMDDHHMMSS 141 notation; 20170827133700 denotes 13:37:00 UTC on August 27th, 2017. A 142 time relative to the ``dsset-`` file is indicated with ``-N``, which is N 143 seconds before the file modification time. A time relative to the 144 current time is indicated with ``now+N``. 145 146 If no start-time is specified, the modification time of the 147 ``dsset-`` file is used. 148 149 .. option:: -T ttl 150 151 This option specifies a TTL to be used for new DS records. If not specified, the 152 default is the TTL of the old DS records. If they had no explicit TTL, 153 the new DS records also have no explicit TTL. 154 155 .. option:: -u 156 157 This option writes an :iscman:`nsupdate` script to the standard output, instead of 158 printing the new DS reords. The output is empty if no change is 159 needed. 160 161 Note: The TTL of new records needs to be specified: it can be done in the 162 original ``dsset-`` file, with the :option:`-T` option, or using the 163 :iscman:`nsupdate` ``ttl`` command. 164 165 .. option:: -V 166 167 This option prints version information. 168 169 .. option:: -v level 170 171 This option sets the debugging level. Level 1 is intended to be usefully verbose 172 for general users; higher levels are intended for developers. 173 174 ``domain`` 175 This indicates the name of the delegation point/child zone apex. 176 177 Exit Status 178 ~~~~~~~~~~~ 179 180 The :program:`dnssec-cds` command exits 0 on success, or non-zero if an error 181 occurred. 182 183 If successful, the DS records may or may not need to be 184 changed. 185 186 Examples 187 ~~~~~~~~ 188 189 Before running :iscman:`dnssec-signzone`, ensure that the delegations 190 are up-to-date by running :program:`dnssec-cds` on every ``dsset-`` file. 191 192 To fetch the child records required by :program:`dnssec-cds`, invoke 193 :iscman:`dig` as in the script below. It is acceptable if the :iscman:`dig` fails, since 194 :program:`dnssec-cds` performs all the necessary checking. 195 196 :: 197 198 for f in dsset-* 199 do 200 d=${f#dsset-} 201 dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS | 202 dnssec-cds -i -f /dev/stdin -d $f $d 203 done 204 205 When the parent zone is automatically signed by :iscman:`named`, 206 :program:`dnssec-cds` can be used with :iscman:`nsupdate` to maintain a delegation as follows. 207 The ``dsset-`` file allows the script to avoid having to fetch and 208 validate the parent DS records, and it maintains the replay attack 209 protection time. 210 211 :: 212 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 217 See Also 218 ~~~~~~~~ 219 220 :iscman:`dig(1) <dig>`, :iscman:`dnssec-settime(8) <dnssec-settime>`, :iscman:`dnssec-signzone(8) <dnssec-signzone>`, :iscman:`nsupdate(1) <nsupdate>`, BIND 9 Administrator 221 Reference Manual, :rfc:`7344`. 222
Indexes created Wed Mar 04 15:26:31 UTC 2026