2 * special zone file structures and functions for better dnssec handling
4 * A zone contains a SOA dnssec_zone_rrset, and an AVL tree of 'normal'
5 * dnssec_zone_rrsets, indexed by name and type
8 #ifndef LDNS_DNSSEC_ZONE_H
9 #define LDNS_DNSSEC_ZONE_H
11 #include <ldns/rbtree.h>
12 #include <ldns/host2str.h>
19 * Singly linked list of rrs
21 typedef struct ldns_struct_dnssec_rrs ldns_dnssec_rrs;
22 struct ldns_struct_dnssec_rrs
25 ldns_dnssec_rrs *next;
29 * Singly linked list of RRsets
31 typedef struct ldns_struct_dnssec_rrsets ldns_dnssec_rrsets;
32 struct ldns_struct_dnssec_rrsets
36 ldns_dnssec_rrs *signatures;
37 ldns_dnssec_rrsets *next;
41 * Structure containing all resource records for a domain name
42 * Including the derived NSEC3, if present
44 typedef struct ldns_struct_dnssec_name ldns_dnssec_name;
45 struct ldns_struct_dnssec_name
48 * pointer to a dname containing the name.
49 * Usually points to the owner name of the first RR of the first RRset
53 * Usually, the name is a pointer to the owner name of the first rr for
54 * this name, but sometimes there is no actual data to point to,
56 * names representing empty nonterminals. If so, set alloced to true to
57 * indicate that this data must also be freed when the name is freed
61 * The rrsets for this name
63 ldns_dnssec_rrsets *rrsets;
65 * NSEC pointing to the next name (or NSEC3 pointing to the next NSEC3)
69 * signatures for the NSEC record
71 ldns_dnssec_rrs *nsec_signatures;
73 * Unlike what the name is_glue suggests, this field is set to true by
74 * ldns_dnssec_zone_mark_glue() or ldns_dnssec_zone_mark_and_get_glue()
75 * when the name, this dnssec_name struct represents, is occluded.
76 * Names that contain other occluded rrsets and records with glue on
77 * the delegation point will NOT have this bool set to true.
78 * This field should NOT be read directly, but only via the
79 * ldns_dnssec_name_is_glue() function!
83 * pointer to store the hashed name (only used when in an NSEC3 zone
85 ldns_rdf *hashed_name;
89 * Structure containing a dnssec zone
91 struct ldns_struct_dnssec_zone {
92 /** points to the name containing the SOA RR */
93 ldns_dnssec_name *soa;
94 /** tree of ldns_dnssec_names */
96 /** tree of ldns_dnssec_names by nsec3 hashes (when applicible) */
97 ldns_rbtree_t *hashed_names;
98 /** points to the first added NSEC3 rr whose parameters will be
99 * assumed for all subsequent NSEC3 rr's and which will be used
100 * to calculate hashed names
102 ldns_rr *_nsec3params;
104 typedef struct ldns_struct_dnssec_zone ldns_dnssec_zone;
107 * Creates a new entry for 1 pointer to an rr and 1 pointer to the next rrs
108 * \return the allocated data
110 ldns_dnssec_rrs *ldns_dnssec_rrs_new(void);
113 * Frees the list of rrs, but *not* the individual ldns_rr records
114 * contained in the list
116 * \param[in] rrs the data structure to free
118 void ldns_dnssec_rrs_free(ldns_dnssec_rrs *rrs);
121 * Frees the list of rrs, and the individual ldns_rr records
122 * contained in the list
124 * \param[in] rrs the data structure to free
126 void ldns_dnssec_rrs_deep_free(ldns_dnssec_rrs *rrs);
129 * Adds an RR to the list of RRs. The list will remain ordered.
130 * If an equal RR already exists, this RR will not be added.
132 * \param[in] rrs the list to add to
133 * \param[in] rr the RR to add
134 * \return LDNS_STATUS_OK on success
136 ldns_status ldns_dnssec_rrs_add_rr(ldns_dnssec_rrs *rrs, ldns_rr *rr);
139 * Prints the given rrs to the file descriptor
141 * \param[in] out the file descriptor to print to
142 * \param[in] rrs the list of RRs to print
144 void ldns_dnssec_rrs_print(FILE *out, const ldns_dnssec_rrs *rrs);
147 * Prints the given rrs to the file descriptor
149 * \param[in] out the file descriptor to print to
150 * \param[in] fmt the format of the textual representation
151 * \param[in] rrs the list of RRs to print
153 void ldns_dnssec_rrs_print_fmt(FILE *out,
154 const ldns_output_format *fmt, const ldns_dnssec_rrs *rrs);
157 * Creates a new list (entry) of RRsets
158 * \return the newly allocated structure
160 ldns_dnssec_rrsets *ldns_dnssec_rrsets_new(void);
163 * Frees the list of rrsets and their rrs, but *not* the ldns_rr
164 * records in the sets
166 * \param[in] rrsets the data structure to free
168 void ldns_dnssec_rrsets_free(ldns_dnssec_rrsets *rrsets);
171 * Frees the list of rrsets and their rrs, and the ldns_rr
172 * records in the sets
174 * \param[in] rrsets the data structure to free
176 void ldns_dnssec_rrsets_deep_free(ldns_dnssec_rrsets *rrsets);
179 * Returns the rr type of the rrset (that is head of the given list)
181 * \param[in] rrsets the rrset to get the type of
182 * \return the rr type
184 ldns_rr_type ldns_dnssec_rrsets_type(const ldns_dnssec_rrsets *rrsets);
187 * Sets the RR type of the rrset (that is head of the given list)
189 * \param[in] rrsets the rrset to set the type of
190 * \param[in] type the type to set
191 * \return LDNS_STATUS_OK on success
193 ldns_status ldns_dnssec_rrsets_set_type(ldns_dnssec_rrsets *rrsets,
197 * Add an ldns_rr to the corresponding RRset in the given list of RRsets.
198 * If it is not present, add it as a new RRset with 1 record.
200 * \param[in] rrsets the list of rrsets to add the RR to
201 * \param[in] rr the rr to add to the list of rrsets
202 * \return LDNS_STATUS_OK on success
204 ldns_status ldns_dnssec_rrsets_add_rr(ldns_dnssec_rrsets *rrsets, ldns_rr *rr);
207 * Print the given list of rrsets to the fiven file descriptor
209 * \param[in] out the file descriptor to print to
210 * \param[in] rrsets the list of RRsets to print
211 * \param[in] follow if set to false, only print the first RRset
213 void ldns_dnssec_rrsets_print(FILE *out,
214 const ldns_dnssec_rrsets *rrsets,
218 * Print the given list of rrsets to the fiven file descriptor
220 * \param[in] out the file descriptor to print to
221 * \param[in] fmt the format of the textual representation
222 * \param[in] rrsets the list of RRsets to print
223 * \param[in] follow if set to false, only print the first RRset
225 void ldns_dnssec_rrsets_print_fmt(FILE *out,
226 const ldns_output_format *fmt,
227 const ldns_dnssec_rrsets *rrsets,
232 * Create a new data structure for a dnssec name
233 * \return the allocated structure
235 ldns_dnssec_name *ldns_dnssec_name_new(void);
238 * Create a new data structure for a dnssec name for the given RR
240 * \param[in] rr the RR to derive properties from, and to add to the name
242 ldns_dnssec_name *ldns_dnssec_name_new_frm_rr(ldns_rr *rr);
245 * Frees the name structure and its rrs and rrsets.
246 * Individual ldns_rr records therein are not freed
248 * \param[in] name the structure to free
250 void ldns_dnssec_name_free(ldns_dnssec_name *name);
253 * Frees the name structure and its rrs and rrsets.
254 * Individual ldns_rr records contained in the name are also freed
256 * \param[in] name the structure to free
258 void ldns_dnssec_name_deep_free(ldns_dnssec_name *name);
261 * Returns the domain name of the given dnssec_name structure
263 * \param[in] name the dnssec name to get the domain name from
264 * \return the domain name
266 ldns_rdf *ldns_dnssec_name_name(const ldns_dnssec_name *name);
270 * Sets the domain name of the given dnssec_name structure
272 * \param[in] name the dnssec name to set the domain name of
273 * \param[in] dname the domain name to set it to. This data is *not* copied.
275 void ldns_dnssec_name_set_name(ldns_dnssec_name *name,
278 * Returns if dnssec_name structure is marked as glue.
279 * The ldns_dnssec_zone_mark_glue() function has to be called on a zone before
280 * using this function.
281 * Only names that have only glue rrsets will be marked.
282 * Names that have other occluded rrsets and names containing glue on the
283 * delegation point will NOT be marked!
285 * \param[in] name the dnssec name to get the domain name from
286 * \return true if the structure is marked as glue, false otherwise.
288 bool ldns_dnssec_name_is_glue(const ldns_dnssec_name *name);
291 * Sets the NSEC(3) RR of the given dnssec_name structure
293 * \param[in] name the dnssec name to set the domain name of
294 * \param[in] nsec the nsec rr to set it to. This data is *not* copied.
296 void ldns_dnssec_name_set_nsec(ldns_dnssec_name *name, ldns_rr *nsec);
299 * Compares the domain names of the two arguments in their
300 * canonical ordening.
302 * \param[in] a The first dnssec_name to compare
303 * \param[in] b The second dnssec_name to compare
304 * \return -1 if the domain name of a comes before that of b in canonical
305 * ordening, 1 if it is the other way around, and 0 if they are
308 int ldns_dnssec_name_cmp(const void *a, const void *b);
311 * Inserts the given rr at the right place in the current dnssec_name
312 * No checking is done whether the name matches
314 * \param[in] name The ldns_dnssec_name to add the RR to
315 * \param[in] rr The RR to add
316 * \return LDNS_STATUS_OK on success, error code otherwise
318 ldns_status ldns_dnssec_name_add_rr(ldns_dnssec_name *name,
322 * Find the RRset with the given type in within this name structure
324 * \param[in] name the name to find the RRset in
325 * \param[in] type the type of the RRset to find
326 * \return the RRset, or NULL if not present
328 ldns_dnssec_rrsets *ldns_dnssec_name_find_rrset(const ldns_dnssec_name *name,
332 * Find the RRset with the given name and type in the zone
334 * \param[in] zone the zone structure to find the RRset in
335 * \param[in] dname the domain name of the RRset to find
336 * \param[in] type the type of the RRset to find
337 * \return the RRset, or NULL if not present
339 ldns_dnssec_rrsets *ldns_dnssec_zone_find_rrset(const ldns_dnssec_zone *zone,
340 const ldns_rdf *dname,
344 * Prints the RRs in the dnssec name structure to the given
347 * \param[in] out the file descriptor to print to
348 * \param[in] name the name structure to print the contents of
350 void ldns_dnssec_name_print(FILE *out, const ldns_dnssec_name *name);
353 * Prints the RRs in the dnssec name structure to the given
356 * \param[in] out the file descriptor to print to
357 * \param[in] fmt the format of the textual representation
358 * \param[in] name the name structure to print the contents of
360 void ldns_dnssec_name_print_fmt(FILE *out,
361 const ldns_output_format *fmt, const ldns_dnssec_name *name);
364 * Creates a new dnssec_zone structure
365 * \return the allocated structure
367 ldns_dnssec_zone *ldns_dnssec_zone_new(void);
370 * Create a new dnssec zone from a file.
371 * \param[out] z the new zone
372 * \param[in] *fp the filepointer to use
373 * \param[in] *origin the zones' origin
374 * \param[in] c default class to use (IN)
375 * \param[in] ttl default ttl to use
377 * \return ldns_status mesg with an error or LDNS_STATUS_OK
379 ldns_status ldns_dnssec_zone_new_frm_fp(ldns_dnssec_zone** z, FILE* fp,
380 const ldns_rdf* origin, uint32_t ttl, ldns_rr_class c);
383 * Create a new dnssec zone from a file, keep track of the line numbering
384 * \param[out] z the new zone
385 * \param[in] *fp the filepointer to use
386 * \param[in] *origin the zones' origin
387 * \param[in] ttl default ttl to use
388 * \param[in] c default class to use (IN)
389 * \param[out] line_nr used for error msg, to get to the line number
391 * \return ldns_status mesg with an error or LDNS_STATUS_OK
393 ldns_status ldns_dnssec_zone_new_frm_fp_l(ldns_dnssec_zone** z, FILE* fp,
394 const ldns_rdf* origin, uint32_t ttl, ldns_rr_class c, int* line_nr);
397 * Frees the given zone structure, and its rbtree of dnssec_names
398 * Individual ldns_rr RRs within those names are *not* freed
399 * \param[in] *zone the zone to free
401 void ldns_dnssec_zone_free(ldns_dnssec_zone *zone);
404 * Frees the given zone structure, and its rbtree of dnssec_names
405 * Individual ldns_rr RRs within those names are also freed
406 * \param[in] *zone the zone to free
408 void ldns_dnssec_zone_deep_free(ldns_dnssec_zone *zone);
411 * Adds the given RR to the zone.
412 * It find whether there is a dnssec_name with that name present.
413 * If so, add it to that, if not create a new one.
414 * Special handling of NSEC and RRSIG provided
416 * \param[in] zone the zone to add the RR to
417 * \param[in] rr The RR to add
418 * \return LDNS_STATUS_OK on success, an error code otherwise
420 ldns_status ldns_dnssec_zone_add_rr(ldns_dnssec_zone *zone,
424 * Prints the rbtree of ldns_dnssec_name structures to the file descriptor
426 * \param[in] out the file descriptor to print the names to
427 * \param[in] tree the tree of ldns_dnssec_name structures to print
428 * \param[in] print_soa if true, print SOA records, if false, skip them
430 void ldns_dnssec_zone_names_print(FILE *out, const ldns_rbtree_t *tree, bool print_soa);
433 * Prints the rbtree of ldns_dnssec_name structures to the file descriptor
435 * \param[in] out the file descriptor to print the names to
436 * \param[in] fmt the format of the textual representation
437 * \param[in] tree the tree of ldns_dnssec_name structures to print
438 * \param[in] print_soa if true, print SOA records, if false, skip them
440 void ldns_dnssec_zone_names_print_fmt(FILE *out, const ldns_output_format *fmt,
441 const ldns_rbtree_t *tree, bool print_soa);
444 * Prints the complete zone to the given file descriptor
446 * \param[in] out the file descriptor to print to
447 * \param[in] zone the dnssec_zone to print
449 void ldns_dnssec_zone_print(FILE *out, const ldns_dnssec_zone *zone);
452 * Prints the complete zone to the given file descriptor
454 * \param[in] out the file descriptor to print to
455 * \param[in] fmt the format of the textual representation
456 * \param[in] zone the dnssec_zone to print
458 void ldns_dnssec_zone_print_fmt(FILE *out,
459 const ldns_output_format *fmt, const ldns_dnssec_zone *zone);
462 * Adds explicit dnssec_name structures for the empty nonterminals
463 * in this zone. (this is needed for NSEC3 generation)
465 * \param[in] zone the zone to check for empty nonterminals
466 * return LDNS_STATUS_OK on success.
468 ldns_status ldns_dnssec_zone_add_empty_nonterminals(ldns_dnssec_zone *zone);
471 * If a NSEC3PARAM is available in the apex, walks the zone and returns true
472 * on the first optout nsec3.
474 * \param[in] zone the zone to check for nsec3 optout records
475 * return true when the zone has at least one nsec3 optout record.
477 bool ldns_dnssec_zone_is_nsec3_optout(const ldns_dnssec_zone* zone);