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