Debian Codegraph @

upstream/debian-unstable/man5/dnssec-trust-anchors.d.5

raw
1 '\" t
2 .TH "DNSSEC\-TRUST\-ANCHORS\&.D" "5" "" "systemd 261~rc3" "dnssec-trust-anchors.d"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 dnssec-trust-anchors.d, systemd.positive, systemd.negative \- DNSSEC trust anchor configuration files
24 .SH "SYNOPSIS"
25 .PP
26 .RS 4
27 /etc/dnssec\-trust\-anchors\&.d/*\&.positive
28 .RE
29 .RS 4
30 /run/dnssec\-trust\-anchors\&.d/*\&.positive
31 .RE
32 .RS 4
33 /usr/local/lib/dnssec\-trust\-anchors\&.d/*\&.positive
34 .RE
35 .RS 4
36 /usr/lib/dnssec\-trust\-anchors\&.d/*\&.positive
37 .RE
38 .RS 4
39 /etc/dnssec\-trust\-anchors\&.d/*\&.negative
40 .RE
41 .RS 4
42 /run/dnssec\-trust\-anchors\&.d/*\&.negative
43 .RE
44 .RS 4
45 /usr/local/lib/dnssec\-trust\-anchors\&.d/*\&.negative
46 .RE
47 .RS 4
48 /usr/lib/dnssec\-trust\-anchors\&.d/*\&.negative
49 .RE
50 .SH "DESCRIPTION"
51 .PP
52 The DNSSEC trust anchor configuration files define positive and negative trust anchors
53 \fBsystemd-resolved.service\fR(8)
54 bases DNSSEC integrity proofs on\&.
55 .SH "POSITIVE TRUST ANCHORS"
56 .PP
57 Positive trust anchor configuration files contain
58 \fBDNSKEY\fR
59 and
60 \fBDS\fR
61 resource record definitions to use as base for DNSSEC integrity proofs\&. See
62 \m[blue]\fBRFC 4035, Section 4\&.4\fR\m[]\&\s-2\u[1]\d\s+2
63 for more information about DNSSEC trust anchors\&.
64 .PP
65 Positive trust anchors are read from files with the suffix
66 \&.positive
67 located in
68 /etc/dnssec\-trust\-anchors\&.d/,
69 /run/dnssec\-trust\-anchors\&.d/
70 and
71 /usr/lib/dnssec\-trust\-anchors\&.d/\&. These directories are searched in the specified order, and a trust anchor file of the same name in an earlier path overrides a trust anchor files in a later path\&. To disable a trust anchor file shipped in
72 /usr/lib/dnssec\-trust\-anchors\&.d/
73 it is sufficient to provide an identically\-named file in
74 /etc/dnssec\-trust\-anchors\&.d/
75 or
76 /run/dnssec\-trust\-anchors\&.d/
77 that is either empty or a symlink to
78 /dev/null
79 ("masked")\&.
80 .PP
81 Positive trust anchor files are simple text files resembling DNS zone files, as documented in
82 \m[blue]\fBRFC 1035, Section 5\fR\m[]\&\s-2\u[2]\d\s+2\&. One
83 \fBDS\fR
84 or
85 \fBDNSKEY\fR
86 resource record may be listed per line\&. Empty lines and lines starting with
87 "#"
88 or
89 ";"
90 are ignored, which may be used for commenting\&. A
91 \fBDS\fR
92 resource record is specified like in the following example:
93 .sp
94 .if n \{\
95 .RS 4
96 .\}
97 .nf
98 \&. IN DS 19036 8 2 49aac11d7b6f6446702e54a1607371607a1a41855200fd2ce1cdde32f24e8fb5
99 .fi
100 .if n \{\
101 .RE
102 .\}
103 .PP
104 The first word specifies the domain, use
105 "\&."
106 for the root domain\&. The domain may be specified with or without trailing dot, which is considered equivalent\&. The second word must be
107 "IN"
108 the third word
109 "DS"\&. The following words specify the key tag, signature algorithm, digest algorithm, followed by the hex\-encoded key fingerprint\&. See
110 \m[blue]\fBRFC 4034, Section 5\fR\m[]\&\s-2\u[3]\d\s+2
111 for details about the precise syntax and meaning of these fields\&.
112 .PP
113 Alternatively,
114 \fBDNSKEY\fR
115 resource records may be used to define trust anchors, like in the following example:
116 .sp
117 .if n \{\
118 .RS 4
119 .\}
120 .nf
121 \&. IN DNSKEY 257 3 8 AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0=
122 .fi
123 .if n \{\
124 .RE
125 .\}
126 .PP
127 The first word specifies the domain again, the second word must be
128 "IN", followed by
129 "DNSKEY"\&. The subsequent words encode the
130 \fBDNSKEY\fR
131 flags, protocol and algorithm fields, followed by the key data encoded in Base64\&. See
132 \m[blue]\fBRFC 4034, Section 2\fR\m[]\&\s-2\u[4]\d\s+2
133 for details about the precise syntax and meaning of these fields\&.
134 .PP
135 If multiple
136 \fBDS\fR
137 or
138 \fBDNSKEY\fR
139 records are defined for the same domain (possibly even in different trust anchor files), all keys are used and are considered equivalent as base for DNSSEC proofs\&.
140 .PP
141 Note that
142 systemd\-resolved
143 will automatically use a built\-in trust anchor key for the Internet root domain if no positive trust anchors are defined for the root domain\&. In most cases it is hence unnecessary to define an explicit key with trust anchor files\&. The built\-in key is disabled as soon as at least one trust anchor key for the root domain is defined in trust anchor files\&.
144 .PP
145 It is generally recommended to encode trust anchors in
146 \fBDS\fR
147 resource records, rather than
148 \fBDNSKEY\fR
149 resource records\&.
150 .PP
151 If a trust anchor specified via a
152 \fBDS\fR
153 record is found revoked it is automatically removed from the trust anchor database for the runtime\&. See
154 \m[blue]\fBRFC 5011\fR\m[]\&\s-2\u[5]\d\s+2
155 for details about revoked trust anchors\&. Note that
156 systemd\-resolved
157 will not update its trust anchor database from DNS servers automatically\&. Instead, it is recommended to update the resolver software or update the new trust anchor via adding in new trust anchor files\&.
158 .PP
159 The current DNSSEC trust anchor for the Internet\*(Aqs root domain is available at the
160 \m[blue]\fBIANA Trust Anchor and Keys\fR\m[]\&\s-2\u[6]\d\s+2
161 page\&.
162 .SH "NEGATIVE TRUST ANCHORS"
163 .PP
164 Negative trust anchors define domains where DNSSEC validation shall be turned off\&. Negative trust anchor files are found at the same location as positive trust anchor files, and follow the same overriding rules\&. They are text files with the
165 \&.negative
166 suffix\&. Empty lines and lines whose first character is
167 ";"
168 are ignored\&. Each line specifies one domain name which is the root of a DNS subtree where validation shall be disabled\&. For example:
169 .sp
170 .if n \{\
171 .RS 4
172 .\}
173 .nf
174 # Reverse IPv4 mappings
175 10\&.in\-addr\&.arpa
176 16\&.172\&.in\-addr\&.arpa
177 168\&.192\&.in\-addr\&.arpa
178 \&.\&.\&.
179 # Some custom domains
180 prod
181 stag
182 .fi
183 .if n \{\
184 .RE
185 .\}
186 .PP
187 Negative trust anchors are useful to support private DNS subtrees that are not referenced from the Internet DNS hierarchy, and not signed\&.
188 .PP
189 \m[blue]\fBRFC 7646\fR\m[]\&\s-2\u[7]\d\s+2
190 for details on negative trust anchors\&.
191 .PP
192 If no negative trust anchor files are configured a built\-in set of well\-known private DNS zone domains is used as negative trust anchors\&.
193 .PP
194 It is also possibly to define per\-interface negative trust anchors using the
195 \fIDNSSECNegativeTrustAnchors=\fR
196 setting in
197 \fBsystemd.network\fR(5)
198 files\&.
199 .SH "SEE ALSO"
200 .PP
201 \fBsystemd\fR(1), \fBsystemd-resolved.service\fR(8), \fBresolved.conf\fR(5), \fBsystemd.network\fR(5)
202 .SH "NOTES"
203 .IP " 1." 4
204 RFC 4035, Section 4.4
205 .RS 4
206 \%https://tools.ietf.org/html/rfc4035#section-4.4
207 .RE
208 .IP " 2." 4
209 RFC 1035, Section 5
210 .RS 4
211 \%https://tools.ietf.org/html/rfc1035#section-5
212 .RE
213 .IP " 3." 4
214 RFC 4034, Section 5
215 .RS 4
216 \%https://tools.ietf.org/html/rfc4034#section-5
217 .RE
218 .IP " 4." 4
219 RFC 4034, Section 2
220 .RS 4
221 \%https://tools.ietf.org/html/rfc4034#section-2
222 .RE
223 .IP " 5." 4
224 RFC 5011
225 .RS 4
226 \%https://tools.ietf.org/html/rfc5011
227 .RE
228 .IP " 6." 4
229 IANA Trust Anchor and Keys
230 .RS 4
231 \%https://data.iana.org/root-anchors/root-anchors.xml
232 .RE
233 .IP " 7." 4
234 RFC 7646
235 .RS 4
236 \%https://tools.ietf.org/html/rfc7646
237 .RE