1dnsval.conf(3) Programmer's Manual dnsval.conf(3)
2
6 dnsval.conf, resolv.conf, root.hints - Configuration policy for the
7 DNSSEC validator library libval(3)
8 val_add_valpolicy - Dynamically add a new policy to the validator
10 context
11 val_remove_valpolicy - Remove a dynamically added policy from the
13 validator context
14
16 int val_add_valpolicy(val_context_t *context,
17 void *policy_definition,
18 val_policy_entry_t **pol);
19 int val_remove_valpolicy(val_context_t *context,
21 val_policy_entry_t *pol);
22 typedef struct {
24 char *keyword;
25 char *zone;
26 char *value;
27 long ttl;
28 } libval_policy_definition_t;
29
31 Applications can use local policy to influence the validation outcome.
32 Examples of local policy elements include trust anchors for different
33 zones and untrusted algorithms for cryptographic keys and hashes.
34 Local policy may vary for different applications and operating
35 scenarios.
36 The val_add_valpolicy() function can be used to dynamically add a new
38 policy for a given context (the policies are not added persistently to
39 the system configuration). The policy_definition field contains an
40 implementation-specific definition of the validator policy to be added.
41 For the libval library this is represented by the
42 libval_policy_definition_t structure, which contains four fields:
43 keyword, zone and value arguments are identical to keyword, zone and
44 additional-data defined below for dnsval.conf. ttl specifies the
45 duration in seconds for which the policy is kept in effect. A tt value
46 of -1 adds to policy to the context indefinitely. A handle to the
47 newly added policy is returned in *pol. This structure is opaque to
48 the applications; applications must not modify the contents of the
49 memory returned in *pol.
50 Applications may also revoke the effects of a newly added policy, pol,
52 before the expiry of its timeout interval using the
53 val_remove_valpolicy() policy.
54 The validator library reads configuration information from three
56 separate files, resolv.conf, root.hints, and dnsval.conf.
57 resolv.conf
59 The nameserver and search options are supported in the resolv.conf
60 file.
61 This nameserver option is used to specify the IP address of the
63 name server to which queries must be sent by default. For example,
64 nameserver 10.0.0.1
66 A number of additional fields can be specified to qualify the name
68 server. For example, in the following line:
69 nameserver [10.0.0.1][example.tsigkey:hmac-md5.sig-alg.reg.int:300:0jnu3SdsMvzzlmTDPYRceA==]:8053
71 example.tsigkey refers to the TSIG key name;
73 hmac-md5.sig-alg.reg.int refers to the TSIG algorithm, 300 is the
74 TSIG fudge factor. and the key is specified as a base64 encoded
75 value. The value 8053 refers to the port number.
76 The values for the TSIG algorithm and the fudge factor in the above
78 example are the defaults. They may be omitted as follows:
79 nameserver [10.0.0.1][example.tsigkey:::0jnu3SdsMvzzlmTDPYRceA==]:8053
81 The TSIG portion may also be left out entirely, in which case the
83 representation is as follows:
84 nameserver [10.0.0.1]:8053
86 This search option is used to specify the search path for issuing
88 queries. For example,
89 search test.dnssec-tools.org dnssec-tools.org
91 The forward option is used to redirect queries for names that match
93 a given zone name to the provided name server. For example,
94 forward 76.216.12.217 test.dnssec-tools.org
96 If the resolv.conf file contains no name servers, the validator
98 tries to recursively answer the query using information present in
99 root.hints.
100 root.hints
102 The root.hints file contains bootstrapping information for the
103 resolver while it attempts to recursively answer queries. The
104 contents of this file may be generated by the following command:
105 dig @e.root-servers.net . ns > root.hints
107 dnsval.conf
109 The dnsval.conf file contains the validator policy. It consists of
110 a sequence of the following "policy-fragments":
111 <label> <keyword> <additional-data>;
113 Policies are identified by simple text strings called labels, which
115 must be unique within the configuration system. For example,
116 "browser" could be used as the label that defines the validator
117 policy for all web-browsers in a system. A label value of ":"
118 identifies the default policy, the policy that is used when a NULL
119 context is specified as the ctx parameter for interfaces listed in
120 libval(3), val_getaddrinfo(3), and val_gethostbyname(3). The
121 default policy must be unique within the configuration system.
122 keyword specifies the policy component within the policy fragment.
124 The format of additional-data depends on the keyword specified.
125 If multiple policy fragments are defined for the same label and
127 keyword combination then the first definition in the file is used.
128 The following keywords are defined for dnsval.conf:
130 trust-anchor
132 For the "trust-anchor" attribute additional-data is a sequence
133 of ordered pairs, each consisting of the zone name and the
134 RDATA portion for the trust anchor with an optional prefix.
135 Trust anchors may be either DNSKEY or DS records, the prefix in
136 the RDATA is use to indicate what type of record it is. DNSKEY
137 is assumed if no prefix is specified.
138 An example is given below.
140 browser trust-anchor
142 . DS 19036 8 2 \
143 49AAC11D7B6F6446702E54A1607371607A1A41855200FD2CE\
144 1CDDE32F24E8FB5
145 example.com 257 3 5 AQO8XS4y9r77X 9SHBmrx MoJf1Pf9\
146 AT9Mr/L5BBGtO9/e9f/zl4FFgM2l B6M2 XEm6mp6 mit4tzp\
147 B/sAEQw1McYz6bJdKkTiqtuWTCfDmgQhI6 /Ha0 Ef GPNSqn\
148 Y 99FmbSeWNIRaa4fgSCVFhvbrYq1nXkNVy QPeEVHk oDNCA\
149 lr qOA3lw==
150 ;
151 zone-security-expectation
153 For the "zone-security-expectation" attribute additional-data
154 is a sequence of <domain name,value> tuples representing the
155 security expectation for names in that domain, where value can
156 be one of the following:
157 ignore
159 Ignore DNSSEC validation for names under this domain.
160 validate
162 Perform DNSSEC validation of answers received for names
163 under this domain.
164 untrusted
166 Reject all answers received for names under this domain.
167 This zone-security-expectation DNSSEC validator policy
169 construct makes it possible to define various islands of trust
170 for DNSSEC-enabled zones and to ignore or validate data from
171 selected zones. The default zone security expectation for a
172 domain is "validate". In the following example, for DNSSEC
173 validator contexts created with a DNSSEC validator policy label
174 of "browser", the DNSSEC validation is only performed for names
175 under the example.com domain; names under the somebogus.org
176 domain are always considered to be untrusted and DNSSEC
177 validation for all other domain names is ignored.
178 browser zone-security-expectation
180 example.com validate
181 somebogusname.org untrusted
182 . ignore
183 ;
184 provably-insecure-status
186 For the "provably-insecure-status" attribute additional-data is
187 a sequence of <domain name,value> tuples representing the
188 validity of the provably insecure condition, where value is one
189 of the following:
190 trusted
192 Treat the provably insecure condition as valid.
193 untrusted
195 Treat the provably insecure condition as invalid.
196 The default value for the provably insecure status for a domain
198 is "trusted". In the following example, for DNSSEC validator
199 contexts created with the default label, the provably insecure
200 condition is treated as valid for all domains except the net
201 domain, where this condition is treated as invalid.
202 : provably-insecure-status
204 . trusted
205 net untrusted
206 ;
207 clock-skew
209 For the "clock-skew" attribute additional-data is a sequence of
210 the domain name and the number of seconds of clock-skew
211 acceptable for signatures on names in that domain. A clock skew
212 value of -1 has the effect of turning off inception and
213 expiration time checks on signatures from that domain. The
214 default clock skew is 0. In the following example, for DNSSEC
215 validator contexts created with the "mta" label, signature
216 inception and expiration checks are disabled for all names
217 under the example.com domain.
218 mta clock-skew
220 example.com -1
221 ;
222 nsec3-max-iter [only if LIBVAL_NSEC3 is enabled]
224 Specifies the maximum number of iterations allowable while
225 computing the NSEC3 hash for a zone. A value of -1 does not
226 place a maximum limit on the number of iterations. This is
227 also the default setting for a zone.
228 dlv-trust-points [only if LIBVAL_DLV is enabled]
230 Specifies the DLV tree for the target zone. In the following
231 example, libval will use the DLV registry defined at
232 dlv.isc.org. for all queries under the root that do not give us
233 a trustworthy answer using the normal DNSSEC mechanism, and
234 have a zone-security-expectation of validate.
235 dlv dlv-trust-points
237 . dlv.isc.org.
238 ;
239 In order for DLV to be used in the above example, there must
241 also be a trust-anchor policy defined for the dlv registry,
242 with the zone-security-expectation policy for registry set to
243 validate.
244 dlv trust-anchor
246 dlv.isc.org DS 19297 5 2 \
247 A11D16F6733983E159EDF8053B2FB57B479D81A309A5\
248 0EAA79A81AF48A47C617
249 ;
250 Apart from zone-specific configuration options, it is also possible
252 to configure global options for the validation in dnsval.conf.
253 Global options can be specified using the construct below.
254 global-options
256 keyowrd1 value1
257 keyword2 value2
258 ...
259 ;
260 There can only be one global-options construct defined for
262 dnsval.conf. If multiple constructs are defined, only the first is
263 used.
264 The following keywords are defined for global-options in
266 dnsval.conf
267 trust-local-answers
269 This option has been deprecated. Use trust-oob-answers instead.
270 trust-oob-answers
272 If the value against this option is yes then, for all answers
273 returned using some out-of-band mechanism (e.g. a file store
274 such as /etc/hosts), the value returned from the
275 val_istrusted() function (see libval(3)) is greater than one.
276 edns0-size
278 In querying various name servers, libsres will also attempt
279 multiple EDNS0 sizes, ending with a query that has EDNS0
280 disabled (i.e. no CD bit set). The following EDNS0 sizes are
281 tried by default: 4096, 1492, 512 The "edns0-size" policy knob
282 can be used to change the largest EDNS0 size that is attempted.
283 env-policy
285 This option allows the administrator of the dnsval.conf to
286 control whether libval uses user-specified values in
287 environmental variables while determining libval policy and log
288 targets. See the section below on overriding dnsval.conf
289 policies for additional details on this option.
290 app-policy
292 This option allows the administrator of the dnsval.conf file to
293 control whether libval will automatically look for a validation
294 policy with a label equal to the application name in
295 dnsval.conf. See the section below on overriding dnsval.conf
296 policies for additional details on this option.
297 closest-ta-only
299 The default validation behavior is to look for any
300 authentication chain that validates successfully. Thus if there
301 are trust anchors for example.com and test.example.com the
302 validator will return success if the authentication chain can
303 be anchored to the example.com trust anchor, even if the trust
304 anchor for test.example.com does not match. In cases where this
305 is not desirable, the closest-ta-only option can be used.
306 If this option is set to yes then the validation algorithm
308 terminates at the closest matching TA.
309 rec-fallback
311 This option is used to control whether libval will attempt to
312 fall back to a recursive lookup of the name if the response
313 from the caching name server returned an error. By default this
314 options is set to yes; it can be turned off by setting this
315 option to no.
316 max-refresh
318 This option is used in conjunction with the
319 VAL_QUERY_SKIP_CACHE query flag. When queries have this flag
320 enabled they would normally skip cached entries. However, max-
321 refresh can throttle how often queries are actually sent on the
322 wire. Whe this option is set to a positive value a new query is
323 only sent out if the cached value was stored more than (the
324 value specified by) max-refresh seconds ago. If max-refresh is
325 0, then the cache is always skipped. If the value is -1 the
326 cache is never skipped. The default value for max-refresh is 60
327 seconds. That means that two queries sent with the the
328 VAL_QUERY_SKIP_CACHE flag set less than a minute apart will
329 only result in one query seen on the wire.
330 proto
332 This option is used to control the network protocol that libval
333 uses to send queries out to various name servers. If the value
334 is set to ipv6, libval uses only IPv6; if it is set to ipv4
335 libval uses only IPv4. The default is any, which causes libval
336 to send over any of the available protocols for the given name
337 server.
338 timeout
340 This option overrides the default resolver timeout value with
341 the value provided.
342 retry
344 This option overrides the default resolver retry value with the
345 value provided.
346 log This option controls the level of logging and the log target
348 for libval. The value expected against this option is the same
349 as that specified for val_add_log_optarg (see libval(3)).
350 An example global-options construct is given below:
352 global-options
354 trust-oob-answers yes
355 edns0-size 4096
356 env-policy enable
357 app-policy enable
358 log 5:stderr
359 ;
360
362 libval first looks at resolver options present in the resolv.conf file
363 specfied at the time of running configure. If this file is absent,
364 libval looks at /etc/resolv.conf file for resolver options.
365 This allows users with a simple way of overriding resolver policies.
367 The system-specific resolv.conf can remain unchanged, while any
368 additional policies that may have to be specified for libval can be
369 used in the configure-supplied resolv.conf file.
370
372 libval provides three ways for tailoring dnsval.conf policies for a
373 given environment.
374 Multiple include files
376 libval allows additional dnsval.conf files to be included with a
377 given dnsval.conf file. The option is specified as follows:
378 include /path/to/override/file/dnsval.conf
380 The files are read in breadth-first. The policies are evaluated in
382 a manner that gives the last-defined policy more precedence over
383 earlier ones. Therefore, an administrator may supply a dnsval.conf
384 with default policies including another file from the user's home
385 directory. The included file may be used for overriding policies
386 specified in the base dnsval.conf file.
387 Application-name policies
389 If the app-policy global option is not disabled, libval
390 automatically looks for a policy in dnsval.conf with a label value
391 constructed from the name of the application. For example,
392 dnsval.conf may be defined with validator policies for the foo
393 label. The foo application, when run, will use the policy defined
394 against the foo label during its validation operation.
395 Policies through environment
397 If the env-policy global option is not disabled, libval looks at
398 the VAL_CONTEXT_LABEL and VAL_LOG_TARGET environmental variables in
399 order to determine the validator policy label and log target.
400 Validator Label Precedence
402 There are effectively four different types of polic-labels that can
403 be applied by libval: application-name policies, policies through
404 VAL_CONTEXT_LABEL, and labels specified by the application (either
405 NULL or non-NULL). The precedence of applying these labels is
406 defined with the following rules:
407 1. If env-policy is "override", use the label specified in the
409 VAL_CONTEXT_LABEL env variable (if defined).
410 2. If env-policy is "enable" and the policy specified by the
412 application is NULL, use the label specified in the
413 VAL_CONTEXT_LABEL env variable (if defined).
414 3. if app-policy is "override", use the label generated from the
416 application name. If this policy label does not exist in the
417 configuration system, use the default policy.
418 4. if app-policy is "enable" and the policy specified by the
420 application is NULL, use the label generated from the application
421 name.
422 5. If policy specified by the application is not NULL, use this
424 label.
425 6. Use default policy
427 The following use-cases can therefore be defined
429 locked-down system with single policy
431 An administrator that wants to (and is able to) lock down a
432 system to a particular validator policy, must set the env-
433 policy and app-policy global options to disable. This also
434 requires that administrators are able to lock down the system
435 to specific applications and that these applications are not
436 written in a way that would allow them to specify non-NULL
437 policy labels during context creation. (see val_create_context
438 in libval(3)).
439 locked-down system with app-specific policies
441 An administrator that wants to (and is able to) lock down a
442 system to a particular dnsval.conf file, but wishes to use
443 different policies for different applications must set the app-
444 policy to override and the env-policy to disable. The
445 administrator must also define policies for various application
446 names in dnval.conf; for applications that don't have a policy
447 with a label corresponding to its name, the default policy is
448 used.
449 The administrator may set the app-policy to enable if non-NULL
451 policies specified by the application during validator context
452 creation is deemed acceptable.
453 User controlled
455 An administrator can set env-policy to override to give the
456 user complete control over which policy label is used during
457 validation. The validation policy is read through the
458 VAL_CONTEXT_LABEL environment variable.
459 If VAL_CONTEXT_LABEL is specified globally for the system, the
461 administrator may instead choose the env-policy global option
462 to be enable instead of override. In this case, the label given
463 in VAL_CONTEXT_LABEL is used only when the policy specified by
464 the application is non-NULL.
465 The label in VAL_CONTEXT_LABEL is used only if it is defined.
467 If this value is NULL, libval will read other policy labels as
468 guided by the precedence rules listed above.
469
471 resolv.conf
472 root.hints
474 dnsval.conf
476
478 Copyright 2004-2013 SPARTA, Inc. All rights reserved. See the COPYING
479 file included with the dnssec-tools package for details.
480
482 libval(3)
483 http://www.dnssec-tools.org http://www.dnssec-tools.org
485perl v5.26.2 2018-08-08 dnsval.conf(3)