1DNSSEC-CDS(1)                       BIND 9                       DNSSEC-CDS(1)
2
3
4

NAME

6       dnssec-cds - change DS records for a child zone based on CDS/CDNSKEY
7

SYNOPSIS

9       dnssec-cds  [-a alg...] [-c class] [-D] {-d dsset-file} {-f child-file}
10       [-i**[extension]] [-s** start-time] [-T ttl] [-u] [-v level] [-V]  {do‐
11       main}
12

DESCRIPTION

14       The  dnssec-cds  command changes DS records at a delegation point based
15       on CDS or CDNSKEY records published in the child zone. If both CDS  and
16       CDNSKEY  records  are  present in the child zone, the CDS is preferred.
17       This enables a child zone to inform its parent of upcoming  changes  to
18       its  key-signing  keys (KSKs); by polling periodically with dnssec-cds,
19       the parent can keep the DS  records  up-to-date  and  enable  automatic
20       rolling of KSKs.
21
22       Two input files are required. The -f child-file option specifies a file
23       containing the child's CDS  and/or  CDNSKEY  records,  plus  RRSIG  and
24       DNSKEY  records  so  that they can be authenticated. The -d path option
25       specifies the location of a file containing the current DS records. For
26       example,  this  could be a dsset- file generated by dnssec-signzone, or
27       the output of dnssec-dsfromkey, or the output  of  a  previous  run  of
28       dnssec-cds.
29
30       The  dnssec-cds  command uses special DNSSEC validation logic specified
31       by RFC 7344. It requires that the CDS and/or CDNSKEY records be validly
32       signed  by  a key represented in the existing DS records. This is typi‐
33       cally the pre-existing KSK.
34
35       For protection against replay attacks,  the  signatures  on  the  child
36       records  must  not  be  older  than  they  were  on  a  previous run of
37       dnssec-cds. Their age is obtained from the modification time of the ds‐
38       set- file, or from the -s option.
39
40       To protect against breaking the delegation, dnssec-cds ensures that the
41       DNSKEY RRset can be verified by every  key  algorithm  in  the  new  DS
42       RRset,  and  that  the  same set of keys are covered by every DS digest
43       type.
44
45       By default, replacement DS records are written to the standard  output;
46       with the -i option the input file is overwritten in place. The replace‐
47       ment DS records are the same as the existing records, when no change is
48       required.  The  output  can be empty if the CDS/CDNSKEY records specify
49       that the child zone wants to be insecure.
50
51       WARNING:
52          Be careful not to delete the DS records when dnssec-cds fails!
53
54       Alternatively, :option`dnssec-cds -u` writes an nsupdate script to  the
55       standard output. The -u and -i options can be used together to maintain
56       a dsset- file as well as emit an nsupdate script.
57

OPTIONS

59       -a algorithm
60              When converting CDS records to DS records, this option specifies
61              the  acceptable  digest algorithms. This option can be repeated,
62              so that multiple digest types are allowed. If none  of  the  CDS
63              records  use  an  acceptable digest type, dnssec-cds will try to
64              use CDNSKEY records instead; if there are no CDNSKEY records, it
65              reports an error.
66
67              When converting CDNSKEY records to DS records, this option spec‐
68              ifies the digest algorithm to use. It can be repeated,  so  that
69              multiple DS records are created for each CDNSKEY records.
70
71              The  algorithm  must be one of SHA-1, SHA-256, or SHA-384. These
72              values are case-insensitive, and the hyphen may be  omitted.  If
73              no algorithm is specified, the default is SHA-256 only.
74
75       -c class
76              This option specifies the DNS class of the zones.
77
78       -D     This  option  generates  DS records from CDNSKEY records if both
79              CDS and CDNSKEY records are present in the child  zone.  By  de‐
80              fault CDS records are preferred.
81
82       -d path
83              This  specifies  the location of the parent DS records. The path
84              can be the name of a file containing the DS records; if it is  a
85              directory, dnssec-cds looks for a dsset- file for the domain in‐
86              side the directory.
87
88              To protect against replay attacks, child records are rejected if
89              they  were  signed earlier than the modification time of the ds‐
90              set- file. This can be adjusted with the -s option.
91
92       -f child-file
93              This option specifies the file containing the child's CDS and/or
94              CDNSKEY  records, plus its DNSKEY records and the covering RRSIG
95              records, so that they can be authenticated.
96
97              The examples below describe how to generate this file.
98
99       -i extension
100              This option updates the dsset- file in place, instead of writing
101              DS records to the standard output.
102
103              There  must  be no space between the -i and the extension. If no
104              extension is provided, the old dsset- is discarded. If an exten‐
105              sion  is  present,  a backup of the old dsset- file is kept with
106              the extension appended to its filename.
107
108              To protect against replay attacks, the modification time of  the
109              dsset-  file is set to match the signature inception time of the
110              child records, provided that it is later than the file's current
111              modification time.
112
113       -s start-time
114              This  option  specifies  the  date  and  time  after which RRSIG
115              records become acceptable. This can be either an absolute  or  a
116              relative  time.  An absolute start time is indicated by a number
117              in YYYYMMDDHHMMSS notation; 20170827133700 denotes 13:37:00  UTC
118              on  August 27th, 2017. A time relative to the dsset- file is in‐
119              dicated with -N, which is N seconds before the file modification
120              time.  A  time  relative  to  the current time is indicated with
121              now+N.
122
123              If no start-time is specified, the modification time of the  ds‐
124              set- file is used.
125
126       -T ttl This  option  specifies  a TTL to be used for new DS records. If
127              not specified, the default is the TTL of the old DS records.  If
128              they  had  no  explicit TTL, the new DS records also have no ex‐
129              plicit TTL.
130
131       -u     This option writes an nsupdate script to  the  standard  output,
132              instead of printing the new DS reords. The output is empty if no
133              change is needed.
134
135              Note: The TTL of new records needs to be specified:  it  can  be
136              done  in  the original dsset- file, with the -T option, or using
137              the nsupdate ttl command.
138
139       -V     This option prints version information.
140
141       -v level
142              This option sets the debugging level. Level 1 is intended to  be
143              usefully  verbose  for general users; higher levels are intended
144              for developers.
145
146       domain This indicates the name of the delegation point/child zone apex.
147

EXIT STATUS

149       The dnssec-cds command exits 0 on success, or non-zero if an error  oc‐
150       curred.
151
152       If successful, the DS records may or may not need to be changed.
153

EXAMPLES

155       Before   running  dnssec-signzone,  ensure  that  the  delegations  are
156       up-to-date by running dnssec-cds on every dsset- file.
157
158       To fetch the child records required by dnssec-cds, invoke dig as in the
159       script  below. It is acceptable if the dig fails, since dnssec-cds per‐
160       forms all the necessary checking.
161
162          for f in dsset-*
163          do
164              d=${f#dsset-}
165              dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
166              dnssec-cds -i -f /dev/stdin -d $f $d
167          done
168
169       When the parent zone is automatically signed by named,  dnssec-cds  can
170       be  used with nsupdate to maintain a delegation as follows.  The dsset-
171       file allows the script to avoid having to fetch and validate the parent
172       DS records, and it maintains the replay attack protection time.
173
174          dig +dnssec +noall +answer $d DNSKEY $d CDNSKEY $d CDS |
175          dnssec-cds -u -i -f /dev/stdin -d $f $d |
176          nsupdate -l
177

SEE ALSO

179       dig(1),  dnssec-settime(8), dnssec-signzone(8), nsupdate(1), BIND 9 Ad‐
180       ministrator Reference Manual, RFC 7344.
181

AUTHOR

183       Internet Systems Consortium
184
186       2023, Internet Systems Consortium
187
188
189
190
1919.18.11                                                          DNSSEC-CDS(1)
Impressum