2 * Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1998-2003 Internet Software Consortium.
5 * Permission to use, copy, modify, and distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
18 /* $Id: rdata.h,v 1.51.2.3.2.4 2004/03/08 02:08:01 marka Exp $ */
30 * Provides facilities for manipulating DNS rdata, including conversions to
31 * and from wire format and text format.
33 * Given the large amount of rdata possible in a nameserver, it was important
34 * to come up with a very efficient way of storing rdata, but at the same
35 * time allow it to be manipulated.
37 * The decision was to store rdata in uncompressed wire format,
38 * and not to make it a fully abstracted object; i.e. certain parts of the
39 * server know rdata is stored that way. This saves a lot of memory, and
40 * makes adding rdata to messages easy. Having much of the server know
41 * the representation would be perilous, and we certainly don't want each
42 * user of rdata to be manipulating such a low-level structure. This is
43 * where the rdata module comes in. The module allows rdata handles to be
44 * created and attached to uncompressed wire format regions. All rdata
45 * operations and conversions are done through these handles.
47 * Implementation Notes:
49 * The routines in this module are expected to be synthesized by the
50 * build process from a set of source files, one per rdata type. For
51 * portability, it's probably best that the building be done by a C
52 * program. Adding a new rdata type will be a simple matter of adding
53 * a file to a directory and rebuilding the server. *All* knowlege of
54 * the format of a particular rdata type is in this file.
57 * Clients of this module must impose any required synchronization.
60 * This module deals with low-level byte streams. Errors in any of
61 * the functions are likely to crash the server or corrupt memory.
63 * Rdata is typed, and the caller must know what type of rdata it has.
64 * A caller that gets this wrong could crash the server.
66 * The fromstruct() and tostruct() routines use a void * pointer to
67 * represent the structure. The caller must ensure that it passes a
68 * pointer to the appropriate type, or the server could crash or memory
78 * dns_rdata_fromwire() deals with raw network data. An error in
79 * this routine could result in the failure or hijacking of the server.
85 * Draft Binary Labels (2)
86 * Draft Local Compression (1)
87 * <Various RFCs for particular types; these will be documented in the
88 * sources files of the types.>
98 #include <dns/types.h>
106 ***** An 'rdata' is a handle to a binary region. The handle has an RR
107 ***** class and type, and the data in the binary region is in the format
108 ***** of the given class and type.
116 * Clients are strongly discouraged from using this type directly, with
117 * the exception of the 'link' field which may be used directly for whatever
118 * purpose the client desires.
121 unsigned char * data;
123 dns_rdataclass_t rdclass;
124 dns_rdatatype_t type;
126 ISC_LINK(dns_rdata_t) link;
129 #define DNS_RDATA_INIT { NULL, 0, 0, 0, 0, {(void*)(-1), (void *)(-1)}}
131 #define DNS_RDATA_UPDATE 0x0001 /* update pseudo record */
134 * Flags affecting rdata formatting style. Flags 0xFFFF0000
135 * are used by masterfile-level formatting and defined elsewhere.
136 * See additional comments at dns_rdata_tofmttext().
139 /* Split the rdata into multiple lines to try to keep it
140 within the "width". */
141 #define DNS_STYLEFLAG_MULTILINE 0x00000001U
143 /* Output explanatory comments. */
144 #define DNS_STYLEFLAG_COMMENT 0x00000002U
146 #define DNS_RDATA_DOWNCASE DNS_NAME_DOWNCASE
147 #define DNS_RDATA_CHECKNAMES DNS_NAME_CHECKNAMES
148 #define DNS_RDATA_CHECKNAMESFAIL DNS_NAME_CHECKNAMESFAIL
149 #define DNS_RDATA_CHECKREVERSE DNS_NAME_CHECKREVERSE
156 dns_rdata_init(dns_rdata_t *rdata);
158 * Make 'rdata' empty.
161 * 'rdata' is a valid rdata (i.e. not NULL, points to a struct dns_rdata)
165 dns_rdata_reset(dns_rdata_t *rdata);
167 * Make 'rdata' empty.
170 * 'rdata' is a previously initialized rdata and is not linked.
174 dns_rdata_clone(const dns_rdata_t *src, dns_rdata_t *target);
176 * Clone 'target' from 'src'.
179 * 'src' to be initialized.
180 * 'target' to be initialized.
188 dns_rdata_compare(const dns_rdata_t *rdata1, const dns_rdata_t *rdata2);
190 * Determine the relative ordering under the DNSSEC order relation of
191 * 'rdata1' and 'rdata2'.
195 * 'rdata1' is a valid, non-empty rdata
197 * 'rdata2' is a valid, non-empty rdata
200 * < 0 'rdata1' is less than 'rdata2'
201 * 0 'rdata1' is equal to 'rdata2'
202 * > 0 'rdata1' is greater than 'rdata2'
210 dns_rdata_fromregion(dns_rdata_t *rdata, dns_rdataclass_t rdclass,
211 dns_rdatatype_t type, isc_region_t *r);
213 * Make 'rdata' refer to region 'r'.
217 * The data in 'r' is properly formatted for whatever type it is.
221 dns_rdata_toregion(const dns_rdata_t *rdata, isc_region_t *r);
223 * Make 'r' refer to 'rdata'.
227 dns_rdata_fromwire(dns_rdata_t *rdata, dns_rdataclass_t rdclass,
228 dns_rdatatype_t type, isc_buffer_t *source,
229 dns_decompress_t *dctx, unsigned int options,
230 isc_buffer_t *target);
232 * Copy the possibly-compressed rdata at source into the target region.
235 * Name decompression policy is controlled by 'dctx'.
238 * DNS_RDATA_DOWNCASE downcase domain names when they are copied
243 * 'rdclass' and 'type' are valid.
245 * 'source' is a valid buffer, and the active region of 'source'
246 * references the rdata to be processed.
248 * 'target' is a valid buffer.
250 * 'dctx' is a valid decompression context.
254 * If result is success:
255 * If 'rdata' is not NULL, it is attached to the target.
257 * The conditions dns_name_fromwire() ensures for names hold
258 * for all names in the rdata.
260 * The current location in source is advanced, and the used space
261 * in target is updated.
265 * <Any non-success status from dns_name_fromwire()>
266 * <Various 'Bad Form' class failures depending on class and type>
267 * Bad Form: Input too short
268 * Resource Limit: Not enough space
272 dns_rdata_towire(dns_rdata_t *rdata, dns_compress_t *cctx,
273 isc_buffer_t *target);
275 * Convert 'rdata' into wire format, compressing it as specified by the
276 * compression context 'cctx', and storing the result in 'target'.
279 * If the compression context allows global compression, then the
280 * global compression table may be updated.
283 * 'rdata' is a valid, non-empty rdata
285 * target is a valid buffer
287 * Any offsets specified in a global compression table are valid
291 * If the result is success:
292 * The used space in target is updated.
296 * <Any non-success status from dns_name_towire()>
297 * Resource Limit: Not enough space
301 dns_rdata_fromtext(dns_rdata_t *rdata, dns_rdataclass_t rdclass,
302 dns_rdatatype_t type, isc_lex_t *lexer, dns_name_t *origin,
303 unsigned int options, isc_mem_t *mctx,
304 isc_buffer_t *target, dns_rdatacallbacks_t *callbacks);
306 * Convert the textual representation of a DNS rdata into uncompressed wire
307 * form stored in the target region. Tokens constituting the text of the rdata
308 * are taken from 'lexer'.
311 * Relative domain names in the rdata will have 'origin' appended to them.
312 * A NULL origin implies "origin == dns_rootname".
316 * DNS_RDATA_DOWNCASE downcase domain names when they are copied
318 * DNS_RDATA_CHECKNAMES perform checknames checks.
319 * DNS_RDATA_CHECKNAMESFAIL fail if the checknames check fail. If
320 * not set a warning will be issued.
321 * DNS_RDATA_CHECKREVERSE this should set if the owner name ends
322 * in IP6.ARPA, IP6.INT or IN-ADDR.ARPA.
326 * 'rdclass' and 'type' are valid.
328 * 'lexer' is a valid isc_lex_t.
330 * 'mctx' is a valid isc_mem_t.
332 * 'target' is a valid region.
334 * 'origin' if non NULL it must be absolute.
336 * 'callbacks' to be NULL or callbacks->warn and callbacks->error be
340 * If result is success:
341 * If 'rdata' is not NULL, it is attached to the target.
343 * The conditions dns_name_fromtext() ensures for names hold
344 * for all names in the rdata.
346 * The used space in target is updated.
350 * <Translated result codes from isc_lex_gettoken>
351 * <Various 'Bad Form' class failures depending on class and type>
352 * Bad Form: Input too short
353 * Resource Limit: Not enough space
354 * Resource Limit: Not enough memory
358 dns_rdata_totext(dns_rdata_t *rdata, dns_name_t *origin, isc_buffer_t *target);
360 * Convert 'rdata' into text format, storing the result in 'target'.
361 * The text will consist of a single line, with fields separated by
365 * If 'origin' is not NULL, then any names in the rdata that are
366 * subdomains of 'origin' will be made relative it.
368 * XXX Do we *really* want to support 'origin'? I'm inclined towards "no"
373 * 'rdata' is a valid, non-empty rdata
375 * 'origin' is NULL, or is a valid name
377 * 'target' is a valid text buffer
380 * If the result is success:
382 * The used space in target is updated.
386 * <Any non-success status from dns_name_totext()>
387 * Resource Limit: Not enough space
391 dns_rdata_tofmttext(dns_rdata_t *rdata, dns_name_t *origin, unsigned int flags,
392 unsigned int width, char *linebreak, isc_buffer_t *target);
394 * Like dns_rdata_totext, but do formatted output suitable for
395 * database dumps. This is intended for use by dns_db_dump();
396 * library users are discouraged from calling it directly.
398 * If (flags & DNS_STYLEFLAG_MULTILINE) != 0, attempt to stay
399 * within 'width' by breaking the text into multiple lines.
400 * The string 'linebreak' is inserted between lines, and parentheses
401 * are added when necessary. Because RRs contain unbreakable elements
402 * such as domain names whose length is variable, unpredictable, and
403 * potentially large, there is no guarantee that the lines will
404 * not exceed 'width' anyway.
406 * If (flags & DNS_STYLEFLAG_MULTILINE) == 0, the rdata is always
407 * printed as a single line, and no parentheses are used.
408 * The 'width' and 'linebreak' arguments are ignored.
410 * If (flags & DNS_STYLEFLAG_COMMENT) != 0, output explanatory
411 * comments next to things like the SOA timer fields. Some
412 * comments (e.g., the SOA ones) are only printed when multiline
413 * output is selected.
417 dns_rdata_fromstruct(dns_rdata_t *rdata, dns_rdataclass_t rdclass,
418 dns_rdatatype_t type, void *source, isc_buffer_t *target);
420 * Convert the C structure representation of an rdata into uncompressed wire
421 * format in 'target'.
423 * XXX Should we have a 'size' parameter as a sanity check on target?
427 * 'rdclass' and 'type' are valid.
429 * 'source' points to a valid C struct for the class and type.
431 * 'target' is a valid buffer.
433 * All structure pointers to memory blocks should be NULL if their
434 * corresponding length values are zero.
437 * If result is success:
438 * If 'rdata' is not NULL, it is attached to the target.
440 * The used space in 'target' is updated.
444 * <Various 'Bad Form' class failures depending on class and type>
445 * Resource Limit: Not enough space
449 dns_rdata_tostruct(dns_rdata_t *rdata, void *target, isc_mem_t *mctx);
451 * Convert an rdata into its C structure representation.
453 * If 'mctx' is NULL then 'rdata' must persist while 'target' is being used.
455 * If 'mctx' is non NULL then memory will be allocated if required.
459 * 'rdata' is a valid, non-empty rdata.
461 * 'target' to point to a valid pointer for the type and class.
465 * Resource Limit: Not enough memory
469 dns_rdata_freestruct(void *source);
471 * Free dynamic memory attached to 'source' (if any).
475 * 'source' to point to the structure previously filled in by
476 * dns_rdata_tostruct().
480 dns_rdatatype_ismeta(dns_rdatatype_t type);
482 * Return true iff the rdata type 'type' is a meta-type
487 dns_rdatatype_issingleton(dns_rdatatype_t type);
489 * Return true iff the rdata type 'type' is a singleton type,
493 * 'type' is a valid rdata type.
498 dns_rdataclass_ismeta(dns_rdataclass_t rdclass);
500 * Return true iff the rdata class 'rdclass' is a meta-class
505 dns_rdatatype_isdnssec(dns_rdatatype_t type);
507 * Return true iff 'type' is one of the DNSSEC
508 * rdata types that may exist alongside a CNAME record.
511 * 'type' is a valid rdata type.
515 dns_rdatatype_iszonecutauth(dns_rdatatype_t type);
517 * Return true iff rdata of type 'type' is considered authoritative
518 * data (not glue) in the NSEC chain when it occurs in the parent zone
522 * 'type' is a valid rdata type.
527 dns_rdatatype_isknown(dns_rdatatype_t type);
529 * Return true iff the rdata type 'type' is known.
532 * 'type' is a valid rdata type.
538 dns_rdata_additionaldata(dns_rdata_t *rdata, dns_additionaldatafunc_t add,
541 * Call 'add' for each name and type from 'rdata' which is subject to
542 * additional section processing.
546 * 'rdata' is a valid, non-empty rdata.
548 * 'add' is a valid dns_additionalfunc_t.
552 * If successful, then add() will have been called for each name
553 * and type subject to additional section processing.
555 * If add() returns something other than ISC_R_SUCCESS, that result
556 * will be returned as the result of dns_rdata_additionaldata().
562 * Many other results are possible if not successful.
566 dns_rdata_digest(dns_rdata_t *rdata, dns_digestfunc_t digest, void *arg);
568 * Send 'rdata' in DNSSEC canonical form to 'digest'.
571 * 'digest' may be called more than once by dns_rdata_digest(). The
572 * concatenation of all the regions, in the order they were given
573 * to 'digest', will be the DNSSEC canonical form of 'rdata'.
577 * 'rdata' is a valid, non-empty rdata.
579 * 'digest' is a valid dns_digestfunc_t.
583 * If successful, then all of the rdata's data has been sent, in
584 * DNSSEC canonical form, to 'digest'.
586 * If digest() returns something other than ISC_R_SUCCESS, that result
587 * will be returned as the result of dns_rdata_digest().
593 * Many other results are possible if not successful.
597 dns_rdatatype_questiononly(dns_rdatatype_t type);
599 * Return true iff rdata of type 'type' can only appear in the question
600 * section of a properly formatted message.
603 * 'type' is a valid rdata type.
608 dns_rdatatype_notquestion(dns_rdatatype_t type);
610 * Return true iff rdata of type 'type' can not appear in the question
611 * section of a properly formatted message.
614 * 'type' is a valid rdata type.
619 dns_rdatatype_atparent(dns_rdatatype_t type);
621 * Return true iff rdata of type 'type' should appear at the parent of
625 * 'type' is a valid rdata type.
630 dns_rdatatype_attributes(dns_rdatatype_t rdtype);
632 * Return attributes for the given type.
635 * 'rdtype' are known.
638 * a bitmask consisting of the following flags.
641 /* only one may exist for a name */
642 #define DNS_RDATATYPEATTR_SINGLETON 0x00000001U
643 /* requires no other data be present */
644 #define DNS_RDATATYPEATTR_EXCLUSIVE 0x00000002U
646 #define DNS_RDATATYPEATTR_META 0x00000004U
647 /* Is a DNSSEC type, like RRSIG or NSEC */
648 #define DNS_RDATATYPEATTR_DNSSEC 0x00000008U
649 /* Is a zone cut authority type */
650 #define DNS_RDATATYPEATTR_ZONECUTAUTH 0x00000010U
651 /* Is reserved (unusable) */
652 #define DNS_RDATATYPEATTR_RESERVED 0x00000020U
653 /* Is an unknown type */
654 #define DNS_RDATATYPEATTR_UNKNOWN 0x00000040U
655 /* Is META, and can only be in a question section */
656 #define DNS_RDATATYPEATTR_QUESTIONONLY 0x00000080U
657 /* is META, and can NOT be in a question section */
658 #define DNS_RDATATYPEATTR_NOTQUESTION 0x00000100U
659 /* Is present at zone cuts in the parent, not the child */
660 #define DNS_RDATATYPEATTR_ATPARENT 0x00000200U
663 dns_rdata_covers(dns_rdata_t *rdata);
665 * Return the rdatatype that this type covers.
668 * 'rdata' is a valid, non-empty rdata.
670 * 'rdata' is a type that covers other rdata types.
677 dns_rdata_checkowner(dns_name_t* name, dns_rdataclass_t rdclass,
678 dns_rdatatype_t type, isc_boolean_t wildcard);
680 * Returns whether this is a valid ownername for this <type,class>.
681 * If wildcard is true allow the first label to be a wildcard if
685 * 'name' is a valid name.
689 dns_rdata_checknames(dns_rdata_t *rdata, dns_name_t *owner, dns_name_t *bad);
691 * Returns whether 'rdata' contains valid domain names. The checks are
692 * sensitive to the owner name.
694 * If 'bad' is non-NULL and a domain name fails the check the
695 * the offending name will be return in 'bad' by cloning from
696 * the 'rdata' contents.
699 * 'rdata' to be valid.
700 * 'owner' to be valid.
701 * 'bad' to be NULL or valid.
706 #endif /* DNS_RDATA_H */