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). val_add_valpolicy - Dynamically
8 add a new policy to the validator context val_remove_valpolicy - Remove
9 a dynamically added policy from the validator context
10
12 int val_add_valpolicy(val_context_t *context,
13 void *policy_definition,
14 val_policy_entry_t **pol);
15 int val_remove_valpolicy(val_context_t *context,
17 val_policy_entry_t *pol);
18 typedef struct {
20 char *keyword;
21 char *zone;
22 char *value;
23 long ttl;
24 } libval_policy_definition_t;
25
27 Applications can use local policy to influence the validation outcome.
28 Examples of local policy elements include trust anchors for different
29 zones and untrusted algorithms for cryptographic keys and hashes.
30 Local policy may vary for different applications and operating scenar‐
31 ios.
32 The val_add_valpolicy() function can be used to dynamically add a new
34 policy for a given context (the policies are not added persistently to
35 the system configuration). The policy_definition field contains an
36 implementation-specific definition of the validator policy to be added.
37 For the libval library this is represented by the libval_policy_defini‐
38 tion_t structure, which contains four fields: keyword, zone and value
39 arguments are identical to keyword, zone and additional-data defined
40 below for dnsval.conf. ttl specifies the duration in seconds for which
41 the policy is kept in effect. A tt value of -1 adds to policy to the
42 context indefinitely. A handle to the newly added policy is returned
43 in *pol. This structure is opaque to the applications; applications
44 must not modify the contents of the memory returned in *pol.
45 Applications may also revoke the effects of a newly added policy, pol,
47 before the expiry of its timeout interval using the val_remove_valpol‐
48 icy() policy.
49 The validator library reads configuration information from three sepa‐
51 rate files, resolv.conf, root.hints, and dnsval.conf.
52 resolv.conf
54 The nameserver and search options are supported in the resolv.conf
55 file.
56 This nameserver option is used to specify the IP address of the
58 name server to which queries must be sent by default. For example,
59 nameserver 10.0.0.1
61 This search option is used to specify the search path for issuing
63 queries. For example,
64 search test.dnssec-tools.org dnssec-tools.org
66 The forward option is used to redirect queries for names that match
68 a given zone name to the provided name server. For example,
69 forward 76.216.12.217 test.dnssec-tools.org
71 If the resolv.conf file contains no name servers, the validator
73 tries to recursively answer the query using information present in
74 root.hints.
75 root.hints
77 The root.hints file contains bootstrapping information for the
78 resolver while it attempts to recursively answer queries. The con‐
79 tents of this file may be generated by the following command:
80 dig @e.root-servers.net . ns > root.hints
82 dnsval.conf
84 The dnsval.conf file contains the validator policy. It consists of
85 a sequence of the following "policy-fragments":
86 <label> <keyword> <additional-data>;
88 Policies are identified by simple text strings called labels, which
90 must be unique within the configuration system. For example,
91 "browser" could be used as the label that defines the validator
92 policy for all web-browsers in a system. A label value of ":"
93 identifies the default policy, the policy that is used when a NULL
94 context is specified as the ctx parameter for interfaces listed in
95 libval(3), val_getaddrinfo(3), and val_gethostbyname(3). The
96 default policy must be unique within the configuration system.
97 keyword specifies the policy component within the policy fragment.
99 The format of additional-data depends on the keyword specified.
100 If multiple policy fragments are defined for the same label and
102 keyword combination then the first definition in the file is used.
103 The following keywords are defined for dnsval.conf:
105 trust-anchor
107 For the "trust-anchor" attribute additional-data is a sequence
108 of ordered pairs, each consisting of the zone name and the
109 RDATA portion for the trust anchor with an optional prefix.
110 Trust anchors may be either DNSKEY or DS records, the prefix in
111 the RDATA is use to indicate what type of record it is. DNSKEY
112 is assumed if no prefix is specified.
113 An example is given below.
115 browser trust-anchor
117 . DS 19036 8 2 \
118 49AAC11D7B6F6446702E54A1607371607A1A41855200FD2CE\
119 1CDDE32F24E8FB5
120 example.com 257 3 5 AQO8XS4y9r77X 9SHBmrx MoJf1Pf9\
121 AT9Mr/L5BBGtO9/e9f/zl4FFgM2l B6M2 XEm6mp6 mit4tzp\
122 B/sAEQw1McYz6bJdKkTiqtuWTCfDmgQhI6 /Ha0 Ef GPNSqn\
123 Y 99FmbSeWNIRaa4fgSCVFhvbrYq1nXkNVy QPeEVHk oDNCA\
124 lr qOA3lw==
125 ;
126 zone-security-expectation
128 For the "zone-security-expectation" attribute additional-data
129 is a sequence of <domain name,value> tuples representing
130 the security expectation for names in that domain, where value
131 can be one of the following:
132 ignore
134 Ignore DNSSEC validation for names under this domain.
135 validate
137 Perform DNSSEC validation of answers received for names
138 under this domain.
139 untrusted
141 Reject all answers received for names under this domain.
142 This zone-security-expectation DNSSEC validator policy con‐
144 struct makes it possible to define various islands of trust for
145 DNSSEC-enabled zones and to ignore or validate data from
146 selected zones. The default zone security expectation for a
147 domain is "validate". In the following example, for DNSSEC
148 validator contexts created with a DNSSEC validator policy label
149 of "browser", the DNSSEC validation is only performed for names
150 under the example.com domain; names under the somebogus.org
151 domain are always considered to be untrusted and DNSSEC valida‐
152 tion for all other domain names is ignored.
153 browser zone-security-expectation
155 example.com validate
156 somebogusname.org untrusted
157 . ignore
158 ;
159 provably-insecure-status
161 For the "provably-insecure-status" attribute additional-data is
162 a sequence of <domain name,value> tuples representing the
163 validity of the provably insecure condition, where value is one
164 of the following:
165 trusted
167 Treat the provably insecure condition as valid.
168 untrusted
170 Treat the provably insecure condition as invalid.
171 The default value for the provably insecure status for a domain
173 is "trusted". In the following example, for DNSSEC validator
174 contexts created with the default label, the provably insecure
175 condition is treated as valid for all domains except the net
176 domain, where this condition is treated as invalid.
177 : provably-insecure-status
179 . trusted
180 net untrusted
181 ;
182 clock-skew
184 For the "clock-skew" attribute additional-data is a sequence of
185 the domain name and the number of seconds of clock-skew accept‐
186 able for signatures on names in that domain. A clock skew value
187 of -1 has the effect of turning off inception and expiration
188 time checks on signatures from that domain. The default clock
189 skew is 0. In the following example, for DNSSEC validator con‐
190 texts created with the "mta" label, signature inception and
191 expiration checks are disabled for all names under the exam‐
192 ple.com domain.
193 mta clock-skew
195 example.com -1
196 ;
197 nsec3-max-iter [only if LIBVAL_NSEC3 is enabled]
199 Specifies the maximum number of iterations allowable while com‐
200 puting the NSEC3 hash for a zone. A value of -1 does not place
201 a maximum limit on the number of iterations. This is also the
202 default setting for a zone.
203 dlv-trust-points [only if LIBVAL_DLV is enabled]
205 Specifies the DLV tree for the target zone. In the following
206 example, libval will use the DLV registry defined at
207 dlv.isc.org. for all queries under the root that do not give us
208 a trustworthy answer using the normal DNSSEC mechanism, and
209 have a zone-security-expectation of validate.
210 dlv dlv-trust-points
212 . dlv.isc.org.
213 ;
214 In order for DLV to be used in the above example, there must
216 also be a trust-anchor policy defined for the dlv registry,
217 with the zone-security-expectation policy for registry set to
218 validate.
219 dlv trust-anchor
221 dlv.isc.org DS 19297 5 2 \
222 A11D16F6733983E159EDF8053B2FB57B479D81A309A5\
223 0EAA79A81AF48A47C617
224 ;
225 Apart from zone-specific configuration options, it is also possible
227 to configure global options for the validation in dnsval.conf.
228 Global options can be specified using the construct below.
229 global-options
231 keyowrd1 value1
232 keyword2 value2
233 ...
234 ;
235 There can only be one global-options construct defined for
237 dnsval.conf. If multiple constructs are defined, only the first is
238 used.
239 The following keywords are defined for global-options in
241 dnsval.conf
242 trust-local-answers
244 This option has been deprecated. Use trust-oob-answers instead.
245 trust-oob-answers
247 If the value against this option is yes then, for all answers
248 returned using some out-of-band mechanism (e.g. a file store
249 such as /etc/hosts), the value returned from the
250 val_istrusted() function (see libval(3)) is greater than one.
251 edns0-size
253 In querying various name servers, libsres will also attempt
254 multiple EDNS0 sizes, ending with a query that has EDNS0 dis‐
255 abled (i.e. no CD bit set). The following EDNS0 sizes are
256 tried by default: 4096, 1492, 512 The "edns0-size" policy knob
257 can be used to change the largest EDNS0 size that is attempted.
258 env-policy
260 This option allows the administrator of the dnsval.conf to con‐
261 trol whether libval uses user-specified values in environmental
262 variables while determining libval policy and log targets. See
263 the section below on overriding dnsval.conf policies for addi‐
264 tional details on this option.
265 app-policy
267 This option allows the administrator of the dnsval.conf file to
268 control whether libval will automatically look for a validation
269 policy with a label equal to the application name in
270 dnsval.conf. See the section below on overriding dnsval.conf
271 policies for additional details on this option.
272 closest-ta-only
274 The default validation behavior is to look for any authentica‐
275 tion chain that validates successfully. Thus if there are trust
276 anchors for example.com and test.example.com the validator will
277 return success if the authentication chain can be anchored to
278 the example.com trust anchor, even if the trust anchor for
279 test.example.com does not match. In cases where this is not
280 desirable, the closest-ta-only option can be used.
281 If this option is set to yes then the validation algorithm ter‐
283 minates at the closest matching TA.
284 rec-fallback
286 This option is used to control whether libval will attempt to
287 fall back to a recursive lookup of the name if the response
288 from the caching name server returned an error. By default this
289 options is set to yes; it can be turned off by setting this
290 option to no.
291 log This option controls the level of logging and the log target
293 for libval. The value expected against this option is the same
294 as that specified for val_add_log_optarg (see libval(3)).
295 An example global-options construct is given below:
297 global-options
299 trust-oob-answers yes
300 edns0-size 4096
301 env-policy enable
302 app-policy enable
303 log 5:stderr
304 ;
305
307 libval first looks at resolver options present in the resolv.conf file
308 specfied at the time of running configure. If this file is absent, lib‐
309 val looks at /etc/resolv.conf file for resolver options.
310 This allows users with a simple way of overriding resolver policies.
312 The system-specific resolv.conf can remain unchanged, while any addi‐
313 tional policies that may have to be specified for libval can be used in
314 the configure-supplied resolv.conf file.
315
317 libval provides three ways for tailoring dnsval.conf policies for a
318 given environment.
319 Multiple include files
321 libval allows additional dnsval.conf files to be included with a
322 given dnsval.conf file. The option is specified as follows:
323 include /path/to/override/file/dnsval.conf
325 The files are read in breadth-first. The policies are evaluated in
327 a manner that gives the last-defined policy more precedence over
328 earlier ones. Therefore, an administrator may supply a dnsval.conf
329 with default policies including another file from the user's home
330 directory. The included file may be used for overriding policies
331 specified in the base dnsval.conf file.
332 Application-name policies
334 If the app-policy global option is not disabled, libval automati‐
335 cally looks for a policy in dnsval.conf with a label value con‐
336 structed from the name of the application. For example,
337 dnsval.conf may be defined with validator policies for the foo
338 label. The foo application, when run, will use the policy defined
339 against the foo label during its validation operation.
340 Policies through environment
342 If the env-policy global option is not disabled, libval looks at
343 the VAL_CONTEXT_LABEL and VAL_LOG_TARGET environmental variables in
344 order to determine the validator policy label and log target.
345 Validator Label Precendence
347 There are effectively four different types of polic-labels that can
348 be applied by libval: application-name policies, policies through
349 VAL_CONTEXT_LABEL, and labels specified by the application (either
350 NULL or non-NULL). The precedence of applying these labels is
351 defined with the following rules:
352 1. If env-policy is "override", use the label specified in the
354 VAL_CONTEXT_LABEL env variable (if defined).
355 2. If env-policy is "enable" and the policy specified by the appli‐
357 cation is NULL, use the label specified in the VAL_CONTEXT_LABEL
358 env variable (if defined).
359 3. if app-policy is "override", use the label generated from the
361 application name. If this policy label does not exist in the con‐
362 figuration system, use the default policy.
363 4. if app-policy is "enable" and the policy specified by the appli‐
365 cation is NULL, use the label generated from the application name.
366 5. If policy specified by the application is not NULL, use this
368 label.
369 6. Use default policy
371 The following use-cases can therefore be defined
373 locked-down system with single policy
375 An administrator that wants to (and is able to) lock down a
376 system to a particular validator policy, must set the env-pol‐
377 icy and app-policy global options to disable. This also
378 requires that administrators are able to lock down the system
379 to specific applications and that these applications are not
380 written in a way that would allow them to specify non-NULL pol‐
381 icy labels during context creation. (see val_create_context in
382 libval(3)).
383 locked-down system with app-specific policies
385 An administrator that wants to (and is able to) lock down a
386 system to a particular dnsval.conf file, but wishes to use dif‐
387 ferent policies for different applications must set the app-
388 policy to override and the env-policy to disable. The adminis‐
389 trator must also define policies for various application names
390 in dnval.conf; for applications that don't have a policy with a
391 label corresponding to its name, the default policy is used.
392 The administrator may set the app-policy to enable if non-NULL
394 policies specified by the application during validator context
395 creation is deemed acceptable.
396 User controlled
398 An administrator can set env-policy to override to give the
399 user complete control over which policy label is used during
400 validation. The validation policy is read through the VAL_CON‐
401 TEXT_LABEL environment variable.
402 If VAL_CONTEXT_LABEL is specified globally for the system, the
404 administrator may instead choose the env-policy global option
405 to be enable instead of override. In this case, the label given
406 in VAL_CONTEXT_LABEL is used only when the policy specified by
407 the application is non-NULL.
408 The label in VAL_CONTEXT_LABEL is used only if it is defined.
410 If this value is NULL, libval will read other policy labels as
411 guided by the precedence rules listed above.
412
414 resolv.conf
415 root.hints
417 dnsval.conf
419
421 Copyright 2004-2011 SPARTA, Inc. All rights reserved. See the COPYING
422 file included with the dnssec-tools package for details.
423
425 libval(3)
426 http://www.dnssec-tools.org http://dnssec-tools.sourceforge.net
428perl v5.8.9 2011-07-06 dnsval.conf(3)