"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.17.5/lib/dns/include/dns/rdata.h" (4 Sep 2020, 22043 Bytes) of package /linux/misc/dns/bind9/9.17.5/bind-9.17.5.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "rdata.h" see the Fossies "Dox" file reference documentation.

    1 /*
    2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    3  *
    4  * This Source Code Form is subject to the terms of the Mozilla Public
    5  * License, v. 2.0. If a copy of the MPL was not distributed with this
    6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
    7  *
    8  * See the COPYRIGHT file distributed with this work for additional
    9  * information regarding copyright ownership.
   10  */
   11 
   12 #ifndef DNS_RDATA_H
   13 #define DNS_RDATA_H 1
   14 
   15 /*****
   16 ***** Module Info
   17 *****/
   18 
   19 /*! \file dns/rdata.h
   20  * \brief
   21  * Provides facilities for manipulating DNS rdata, including conversions to
   22  * and from wire format and text format.
   23  *
   24  * Given the large amount of rdata possible in a nameserver, it was important
   25  * to come up with a very efficient way of storing rdata, but at the same
   26  * time allow it to be manipulated.
   27  *
   28  * The decision was to store rdata in uncompressed wire format,
   29  * and not to make it a fully abstracted object; i.e. certain parts of the
   30  * server know rdata is stored that way.  This saves a lot of memory, and
   31  * makes adding rdata to messages easy.  Having much of the server know
   32  * the representation would be perilous, and we certainly don't want each
   33  * user of rdata to be manipulating such a low-level structure.  This is
   34  * where the rdata module comes in.  The module allows rdata handles to be
   35  * created and attached to uncompressed wire format regions.  All rdata
   36  * operations and conversions are done through these handles.
   37  *
   38  * Implementation Notes:
   39  *
   40  *\li   The routines in this module are expected to be synthesized by the
   41  *  build process from a set of source files, one per rdata type.  For
   42  *  portability, it's probably best that the building be done by a C
   43  *  program.  Adding a new rdata type will be a simple matter of adding
   44  *  a file to a directory and rebuilding the server.  *All* knowledge of
   45  *  the format of a particular rdata type is in this file.
   46  *
   47  * MP:
   48  *\li   Clients of this module must impose any required synchronization.
   49  *
   50  * Reliability:
   51  *\li   This module deals with low-level byte streams.  Errors in any of
   52  *  the functions are likely to crash the server or corrupt memory.
   53  *
   54  *\li   Rdata is typed, and the caller must know what type of rdata it has.
   55  *  A caller that gets this wrong could crash the server.
   56  *
   57  *\li   The fromstruct() and tostruct() routines use a void * pointer to
   58  *  represent the structure.  The caller must ensure that it passes a
   59  *  pointer to the appropriate type, or the server could crash or memory
   60  *  could be corrupted.
   61  *
   62  * Resources:
   63  *\li   None.
   64  *
   65  * Security:
   66  *
   67  *\li   *** WARNING ***
   68  *  dns_rdata_fromwire() deals with raw network data.  An error in
   69  *  this routine could result in the failure or hijacking of the server.
   70  *
   71  * Standards:
   72  *\li   RFC1035
   73  *\li   Draft EDNS0 (0)
   74  *\li   Draft EDNS1 (0)
   75  *\li   Draft Binary Labels (2)
   76  *\li   Draft Local Compression (1)
   77  *\li   Various RFCs for particular types; these will be documented in the
   78  *   sources files of the types.
   79  *
   80  */
   81 
   82 /***
   83  *** Imports
   84  ***/
   85 
   86 #include <stdbool.h>
   87 
   88 #include <isc/lang.h>
   89 
   90 #include <dns/message.h>
   91 #include <dns/name.h>
   92 #include <dns/types.h>
   93 
   94 ISC_LANG_BEGINDECLS
   95 
   96 /***
   97  *** Types
   98  ***/
   99 
  100 /*%
  101  ***** An 'rdata' is a handle to a binary region.  The handle has an RR
  102  ***** class and type, and the data in the binary region is in the format
  103  ***** of the given class and type.
  104  *****/
  105 /*%
  106  * Clients are strongly discouraged from using this type directly, with
  107  * the exception of the 'link' field which may be used directly for whatever
  108  * purpose the client desires.
  109  */
  110 struct dns_rdata {
  111     unsigned char *  data;
  112     unsigned int     length;
  113     dns_rdataclass_t rdclass;
  114     dns_rdatatype_t  type;
  115     unsigned int     flags;
  116     ISC_LINK(dns_rdata_t) link;
  117 };
  118 
  119 #define DNS_RDATA_INIT                                           \
  120     {                                                        \
  121         NULL, 0, 0, 0, 0, { (void *)(-1), (void *)(-1) } \
  122     }
  123 
  124 #define DNS_RDATA_CHECKINITIALIZED
  125 #ifdef DNS_RDATA_CHECKINITIALIZED
  126 #define DNS_RDATA_INITIALIZED(rdata)                                           \
  127     ((rdata)->data == NULL && (rdata)->length == 0 &&                      \
  128      (rdata)->rdclass == 0 && (rdata)->type == 0 && (rdata)->flags == 0 && \
  129      !ISC_LINK_LINKED((rdata), link))
  130 #else /* ifdef DNS_RDATA_CHECKINITIALIZED */
  131 #ifdef ISC_LIST_CHECKINIT
  132 #define DNS_RDATA_INITIALIZED(rdata) (!ISC_LINK_LINKED((rdata), link))
  133 #else /* ifdef ISC_LIST_CHECKINIT */
  134 #define DNS_RDATA_INITIALIZED(rdata) true
  135 #endif /* ifdef ISC_LIST_CHECKINIT */
  136 #endif /* ifdef DNS_RDATA_CHECKINITIALIZED */
  137 
  138 #define DNS_RDATA_UPDATE  0x0001 /*%< update pseudo record. */
  139 #define DNS_RDATA_OFFLINE 0x0002 /*%< RRSIG has a offline key. */
  140 
  141 #define DNS_RDATA_VALIDFLAGS(rdata) \
  142     (((rdata)->flags & ~(DNS_RDATA_UPDATE | DNS_RDATA_OFFLINE)) == 0)
  143 
  144 /*
  145  * The maximum length of a RDATA that can be sent on the wire.
  146  * Max packet size (65535) less header (12), less name (1), type (2),
  147  * class (2), ttl(4), length (2).
  148  *
  149  * None of the defined types that support name compression can exceed
  150  * this and all new types are to be sent uncompressed.
  151  */
  152 
  153 #define DNS_RDATA_MAXLENGTH 65512U
  154 
  155 /*
  156  * Flags affecting rdata formatting style.  Flags 0xFFFF0000
  157  * are used by masterfile-level formatting and defined elsewhere.
  158  * See additional comments at dns_rdata_tofmttext().
  159  */
  160 
  161 /*% Split the rdata into multiple lines to try to keep it
  162  * within the "width". */
  163 #define DNS_STYLEFLAG_MULTILINE 0x00000001ULL
  164 
  165 /*% Output explanatory comments. */
  166 #define DNS_STYLEFLAG_COMMENT   0x00000002ULL
  167 #define DNS_STYLEFLAG_RRCOMMENT 0x00000004ULL
  168 
  169 /*% Output KEYDATA in human readable format. */
  170 #define DNS_STYLEFLAG_KEYDATA 0x00000008ULL
  171 
  172 /*% Output textual RR type and RDATA in RFC 3597 unknown format */
  173 #define DNS_STYLEFLAG_UNKNOWNFORMAT 0x00000010ULL
  174 
  175 /*% Print AAAA record fully expanded */
  176 #define DNS_STYLEFLAG_EXPANDAAAA 0x00000020ULL
  177 
  178 #define DNS_RDATA_DOWNCASE   DNS_NAME_DOWNCASE
  179 #define DNS_RDATA_CHECKNAMES     DNS_NAME_CHECKNAMES
  180 #define DNS_RDATA_CHECKNAMESFAIL DNS_NAME_CHECKNAMESFAIL
  181 #define DNS_RDATA_CHECKREVERSE   DNS_NAME_CHECKREVERSE
  182 #define DNS_RDATA_CHECKMX    DNS_NAME_CHECKMX
  183 #define DNS_RDATA_CHECKMXFAIL    DNS_NAME_CHECKMXFAIL
  184 #define DNS_RDATA_UNKNOWNESCAPE  0x80000000
  185 
  186 /***
  187  *** Initialization
  188  ***/
  189 
  190 void
  191 dns_rdata_init(dns_rdata_t *rdata);
  192 /*%<
  193  * Make 'rdata' empty.
  194  *
  195  * Requires:
  196  *  'rdata' is a valid rdata (i.e. not NULL, points to a struct dns_rdata)
  197  */
  198 
  199 void
  200 dns_rdata_reset(dns_rdata_t *rdata);
  201 /*%<
  202  * Make 'rdata' empty.
  203  *
  204  * Requires:
  205  *\li   'rdata' is a previously initialized rdata and is not linked.
  206  */
  207 
  208 void
  209 dns_rdata_clone(const dns_rdata_t *src, dns_rdata_t *target);
  210 /*%<
  211  * Clone 'target' from 'src'.
  212  *
  213  * Requires:
  214  *\li   'src' to be initialized.
  215  *\li   'target' to be initialized.
  216  */
  217 
  218 /***
  219  *** Comparisons
  220  ***/
  221 
  222 int
  223 dns_rdata_compare(const dns_rdata_t *rdata1, const dns_rdata_t *rdata2);
  224 /*%<
  225  * Determine the relative ordering under the DNSSEC order relation of
  226  * 'rdata1' and 'rdata2'.
  227  *
  228  * Requires:
  229  *
  230  *\li   'rdata1' is a valid, non-empty rdata
  231  *
  232  *\li   'rdata2' is a valid, non-empty rdata
  233  *
  234  * Returns:
  235  *\li   < 0     'rdata1' is less than 'rdata2'
  236  *\li   0       'rdata1' is equal to 'rdata2'
  237  *\li   > 0     'rdata1' is greater than 'rdata2'
  238  */
  239 
  240 int
  241 dns_rdata_casecompare(const dns_rdata_t *rdata1, const dns_rdata_t *rdata2);
  242 /*%<
  243  * dns_rdata_casecompare() is similar to dns_rdata_compare() but also
  244  * compares domain names case insensitively in known rdata types that
  245  * are treated as opaque data by dns_rdata_compare().
  246  *
  247  * Requires:
  248  *
  249  *\li   'rdata1' is a valid, non-empty rdata
  250  *
  251  *\li   'rdata2' is a valid, non-empty rdata
  252  *
  253  * Returns:
  254  *\li   < 0     'rdata1' is less than 'rdata2'
  255  *\li   0       'rdata1' is equal to 'rdata2'
  256  *\li   > 0     'rdata1' is greater than 'rdata2'
  257  */
  258 
  259 /***
  260  *** Conversions
  261  ***/
  262 
  263 void
  264 dns_rdata_fromregion(dns_rdata_t *rdata, dns_rdataclass_t rdclass,
  265              dns_rdatatype_t type, isc_region_t *r);
  266 /*%<
  267  * Make 'rdata' refer to region 'r'.
  268  *
  269  * Requires:
  270  *
  271  *\li   The data in 'r' is properly formatted for whatever type it is.
  272  */
  273 
  274 void
  275 dns_rdata_toregion(const dns_rdata_t *rdata, isc_region_t *r);
  276 /*%<
  277  * Make 'r' refer to 'rdata'.
  278  */
  279 
  280 isc_result_t
  281 dns_rdata_fromwire(dns_rdata_t *rdata, dns_rdataclass_t rdclass,
  282            dns_rdatatype_t type, isc_buffer_t *source,
  283            dns_decompress_t *dctx, unsigned int options,
  284            isc_buffer_t *target);
  285 /*%<
  286  * Copy the possibly-compressed rdata at source into the target region.
  287  *
  288  * Notes:
  289  *\li   Name decompression policy is controlled by 'dctx'.
  290  *
  291  *  'options'
  292  *\li   DNS_RDATA_DOWNCASE  downcase domain names when they are copied
  293  *              into target.
  294  *
  295  * Requires:
  296  *
  297  *\li   'rdclass' and 'type' are valid.
  298  *
  299  *\li   'source' is a valid buffer, and the active region of 'source'
  300  *  references the rdata to be processed.
  301  *
  302  *\li   'target' is a valid buffer.
  303  *
  304  *\li   'dctx' is a valid decompression context.
  305  *
  306  * Ensures,
  307  *  if result is success:
  308  *  \li     If 'rdata' is not NULL, it is attached to the target.
  309  *  \li The conditions dns_name_fromwire() ensures for names hold
  310  *      for all names in the rdata.
  311  *  \li The current location in source is advanced, and the used space
  312  *      in target is updated.
  313  *
  314  * Result:
  315  *\li   Success
  316  *\li   Any non-success status from dns_name_fromwire()
  317  *\li   Various 'Bad Form' class failures depending on class and type
  318  *\li   Bad Form: Input too short
  319  *\li   Resource Limit: Not enough space
  320  */
  321 
  322 isc_result_t
  323 dns_rdata_towire(dns_rdata_t *rdata, dns_compress_t *cctx,
  324          isc_buffer_t *target);
  325 /*%<
  326  * Convert 'rdata' into wire format, compressing it as specified by the
  327  * compression context 'cctx', and storing the result in 'target'.
  328  *
  329  * Notes:
  330  *\li   If the compression context allows global compression, then the
  331  *  global compression table may be updated.
  332  *
  333  * Requires:
  334  *\li   'rdata' is a valid, non-empty rdata
  335  *
  336  *\li   target is a valid buffer
  337  *
  338  *\li   Any offsets specified in a global compression table are valid
  339  *  for target.
  340  *
  341  * Ensures,
  342  *  if the result is success:
  343  *  \li The used space in target is updated.
  344  *
  345  * Returns:
  346  *\li   Success
  347  *\li   Any non-success status from dns_name_towire()
  348  *\li   Resource Limit: Not enough space
  349  */
  350 
  351 isc_result_t
  352 dns_rdata_fromtext(dns_rdata_t *rdata, dns_rdataclass_t rdclass,
  353            dns_rdatatype_t type, isc_lex_t *lexer,
  354            const dns_name_t *origin, unsigned int options,
  355            isc_mem_t *mctx, isc_buffer_t *target,
  356            dns_rdatacallbacks_t *callbacks);
  357 /*%<
  358  * Convert the textual representation of a DNS rdata into uncompressed wire
  359  * form stored in the target region.  Tokens constituting the text of the rdata
  360  * are taken from 'lexer'.
  361  *
  362  * Notes:
  363  *\li   Relative domain names in the rdata will have 'origin' appended to them.
  364  *  A NULL origin implies "origin == dns_rootname".
  365  *
  366  *
  367  *  'options'
  368  *\li   DNS_RDATA_DOWNCASE  downcase domain names when they are copied
  369  *              into target.
  370  *\li   DNS_RDATA_CHECKNAMES    perform checknames checks.
  371  *\li   DNS_RDATA_CHECKNAMESFAIL fail if the checknames check fail.  If
  372  *              not set a warning will be issued.
  373  *\li   DNS_RDATA_CHECKREVERSE  this should set if the owner name ends
  374  *              in IP6.ARPA, IP6.INT or IN-ADDR.ARPA.
  375  *
  376  * Requires:
  377  *
  378  *\li   'rdclass' and 'type' are valid.
  379  *
  380  *\li   'lexer' is a valid isc_lex_t.
  381  *
  382  *\li   'mctx' is a valid isc_mem_t.
  383  *
  384  *\li   'target' is a valid region.
  385  *
  386  *\li   'origin' if non NULL it must be absolute.
  387  *
  388  *\li   'callbacks' to be NULL or callbacks->warn and callbacks->error be
  389  *  initialized.
  390  *
  391  * Ensures,
  392  *  if result is success:
  393  *\li       If 'rdata' is not NULL, it is attached to the target.
  394  *
  395  *\li       The conditions dns_name_fromtext() ensures for names hold
  396  *      for all names in the rdata.
  397  *
  398  *\li       The used space in target is updated.
  399  *
  400  * Result:
  401  *\li   Success
  402  *\li   Translated result codes from isc_lex_gettoken
  403  *\li   Various 'Bad Form' class failures depending on class and type
  404  *\li   Bad Form: Input too short
  405  *\li   Resource Limit: Not enough space
  406  *\li   Resource Limit: Not enough memory
  407  */
  408 
  409 isc_result_t
  410 dns_rdata_totext(dns_rdata_t *rdata, const dns_name_t *origin,
  411          isc_buffer_t *target);
  412 /*%<
  413  * Convert 'rdata' into text format, storing the result in 'target'.
  414  * The text will consist of a single line, with fields separated by
  415  * single spaces.
  416  *
  417  * Notes:
  418  *\li   If 'origin' is not NULL, then any names in the rdata that are
  419  *  subdomains of 'origin' will be made relative it.
  420  *
  421  *\li   XXX Do we *really* want to support 'origin'?  I'm inclined towards "no"
  422  *  at the moment.
  423  *
  424  * Requires:
  425  *
  426  *\li   'rdata' is a valid, non-empty rdata
  427  *
  428  *\li   'origin' is NULL, or is a valid name
  429  *
  430  *\li   'target' is a valid text buffer
  431  *
  432  * Ensures,
  433  *  if the result is success:
  434  *
  435  *  \li The used space in target is updated.
  436  *
  437  * Returns:
  438  *\li   Success
  439  *\li   Any non-success status from dns_name_totext()
  440  *\li   Resource Limit: Not enough space
  441  */
  442 
  443 isc_result_t
  444 dns_rdata_tofmttext(dns_rdata_t *rdata, const dns_name_t *origin,
  445             dns_masterstyle_flags_t flags, unsigned int width,
  446             unsigned int split_width, const char *linebreak,
  447             isc_buffer_t *target);
  448 /*%<
  449  * Like dns_rdata_totext, but do formatted output suitable for
  450  * database dumps.  This is intended for use by dns_db_dump();
  451  * library users are discouraged from calling it directly.
  452  *
  453  * If (flags & #DNS_STYLEFLAG_MULTILINE) != 0, attempt to stay
  454  * within 'width' by breaking the text into multiple lines.
  455  * The string 'linebreak' is inserted between lines, and parentheses
  456  * are added when necessary.  Because RRs contain unbreakable elements
  457  * such as domain names whose length is variable, unpredictable, and
  458  * potentially large, there is no guarantee that the lines will
  459  * not exceed 'width' anyway.
  460  *
  461  * If (flags & #DNS_STYLEFLAG_MULTILINE) == 0, the rdata is always
  462  * printed as a single line, and no parentheses are used.
  463  * The 'width' and 'linebreak' arguments are ignored.
  464  *
  465  * If (flags & #DNS_STYLEFLAG_COMMENT) != 0, output explanatory
  466  * comments next to things like the SOA timer fields.  Some
  467  * comments (e.g., the SOA ones) are only printed when multiline
  468  * output is selected.
  469  *
  470  * base64 rdata text (e.g., DNSKEY records) will be split into chunks
  471  * of 'split_width' characters.  If split_width == 0, the text will
  472  * not be split at all.  If split_width == UINT_MAX (0xffffffff), then
  473  * it is undefined and falls back to the default value of 'width'
  474  */
  475 
  476 isc_result_t
  477 dns_rdata_fromstruct(dns_rdata_t *rdata, dns_rdataclass_t rdclass,
  478              dns_rdatatype_t type, void *source, isc_buffer_t *target);
  479 /*%<
  480  * Convert the C structure representation of an rdata into uncompressed wire
  481  * format in 'target'.
  482  *
  483  * XXX  Should we have a 'size' parameter as a sanity check on target?
  484  *
  485  * Requires:
  486  *
  487  *\li   'rdclass' and 'type' are valid.
  488  *
  489  *\li   'source' points to a valid C struct for the class and type.
  490  *
  491  *\li   'target' is a valid buffer.
  492  *
  493  *\li   All structure pointers to memory blocks should be NULL if their
  494  *  corresponding length values are zero.
  495  *
  496  * Ensures,
  497  *  if result is success:
  498  *  \li     If 'rdata' is not NULL, it is attached to the target.
  499  *
  500  *  \li The used space in 'target' is updated.
  501  *
  502  * Result:
  503  *\li   Success
  504  *\li   Various 'Bad Form' class failures depending on class and type
  505  *\li   Resource Limit: Not enough space
  506  */
  507 
  508 isc_result_t
  509 dns_rdata_tostruct(const dns_rdata_t *rdata, void *target, isc_mem_t *mctx);
  510 /*%<
  511  * Convert an rdata into its C structure representation.
  512  *
  513  * If 'mctx' is NULL then 'rdata' must persist while 'target' is being used.
  514  *
  515  * If 'mctx' is non NULL then memory will be allocated if required.
  516  *
  517  * Requires:
  518  *
  519  *\li   'rdata' is a valid, non-empty rdata.
  520  *
  521  *\li   'target' to point to a valid pointer for the type and class.
  522  *
  523  * Result:
  524  *\li   Success
  525  *\li   Resource Limit: Not enough memory
  526  */
  527 
  528 void
  529 dns_rdata_freestruct(void *source);
  530 /*%<
  531  * Free dynamic memory attached to 'source' (if any).
  532  *
  533  * Requires:
  534  *
  535  *\li   'source' to point to the structure previously filled in by
  536  *  dns_rdata_tostruct().
  537  */
  538 
  539 bool
  540 dns_rdatatype_ismeta(dns_rdatatype_t type);
  541 /*%<
  542  * Return true iff the rdata type 'type' is a meta-type
  543  * like ANY or AXFR.
  544  */
  545 
  546 bool
  547 dns_rdatatype_issingleton(dns_rdatatype_t type);
  548 /*%<
  549  * Return true iff the rdata type 'type' is a singleton type,
  550  * like CNAME or SOA.
  551  *
  552  * Requires:
  553  * \li  'type' is a valid rdata type.
  554  *
  555  */
  556 
  557 bool
  558 dns_rdataclass_ismeta(dns_rdataclass_t rdclass);
  559 /*%<
  560  * Return true iff the rdata class 'rdclass' is a meta-class
  561  * like ANY or NONE.
  562  */
  563 
  564 bool
  565 dns_rdatatype_isdnssec(dns_rdatatype_t type);
  566 /*%<
  567  * Return true iff 'type' is one of the DNSSEC
  568  * rdata types that may exist alongside a CNAME record.
  569  *
  570  * Requires:
  571  * \li  'type' is a valid rdata type.
  572  */
  573 
  574 bool
  575 dns_rdatatype_iszonecutauth(dns_rdatatype_t type);
  576 /*%<
  577  * Return true iff rdata of type 'type' is considered authoritative
  578  * data (not glue) in the NSEC chain when it occurs in the parent zone
  579  * at a zone cut.
  580  *
  581  * Requires:
  582  * \li  'type' is a valid rdata type.
  583  *
  584  */
  585 
  586 bool
  587 dns_rdatatype_isknown(dns_rdatatype_t type);
  588 /*%<
  589  * Return true iff the rdata type 'type' is known.
  590  *
  591  * Requires:
  592  * \li  'type' is a valid rdata type.
  593  *
  594  */
  595 
  596 isc_result_t
  597 dns_rdata_additionaldata(dns_rdata_t *rdata, dns_additionaldatafunc_t add,
  598              void *arg);
  599 /*%<
  600  * Call 'add' for each name and type from 'rdata' which is subject to
  601  * additional section processing.
  602  *
  603  * Requires:
  604  *
  605  *\li   'rdata' is a valid, non-empty rdata.
  606  *
  607  *\li   'add' is a valid dns_additionalfunc_t.
  608  *
  609  * Ensures:
  610  *
  611  *\li   If successful, then add() will have been called for each name
  612  *  and type subject to additional section processing.
  613  *
  614  *\li   If add() returns something other than #ISC_R_SUCCESS, that result
  615  *  will be returned as the result of dns_rdata_additionaldata().
  616  *
  617  * Returns:
  618  *
  619  *\li   ISC_R_SUCCESS
  620  *
  621  *\li   Many other results are possible if not successful.
  622  */
  623 
  624 isc_result_t
  625 dns_rdata_digest(dns_rdata_t *rdata, dns_digestfunc_t digest, void *arg);
  626 /*%<
  627  * Send 'rdata' in DNSSEC canonical form to 'digest'.
  628  *
  629  * Note:
  630  *\li   'digest' may be called more than once by dns_rdata_digest().  The
  631  *  concatenation of all the regions, in the order they were given
  632  *  to 'digest', will be the DNSSEC canonical form of 'rdata'.
  633  *
  634  * Requires:
  635  *
  636  *\li   'rdata' is a valid, non-empty rdata.
  637  *
  638  *\li   'digest' is a valid dns_digestfunc_t.
  639  *
  640  * Ensures:
  641  *
  642  *\li   If successful, then all of the rdata's data has been sent, in
  643  *  DNSSEC canonical form, to 'digest'.
  644  *
  645  *\li   If digest() returns something other than ISC_R_SUCCESS, that result
  646  *  will be returned as the result of dns_rdata_digest().
  647  *
  648  * Returns:
  649  *
  650  *\li   ISC_R_SUCCESS
  651  *
  652  *\li   Many other results are possible if not successful.
  653  */
  654 
  655 bool
  656 dns_rdatatype_questiononly(dns_rdatatype_t type);
  657 /*%<
  658  * Return true iff rdata of type 'type' can only appear in the question
  659  * section of a properly formatted message.
  660  *
  661  * Requires:
  662  * \li  'type' is a valid rdata type.
  663  *
  664  */
  665 
  666 bool
  667 dns_rdatatype_notquestion(dns_rdatatype_t type);
  668 /*%<
  669  * Return true iff rdata of type 'type' can not appear in the question
  670  * section of a properly formatted message.
  671  *
  672  * Requires:
  673  * \li  'type' is a valid rdata type.
  674  *
  675  */
  676 
  677 bool
  678 dns_rdatatype_atparent(dns_rdatatype_t type);
  679 /*%<
  680  * Return true iff rdata of type 'type' should appear at the parent of
  681  * a zone cut.
  682  *
  683  * Requires:
  684  * \li  'type' is a valid rdata type.
  685  *
  686  */
  687 
  688 bool
  689 dns_rdatatype_atcname(dns_rdatatype_t type);
  690 /*%<
  691  * Return true iff rdata of type 'type' can appear beside a cname.
  692  *
  693  * Requires:
  694  * \li  'type' is a valid rdata type.
  695  *
  696  */
  697 
  698 unsigned int
  699 dns_rdatatype_attributes(dns_rdatatype_t rdtype);
  700 /*%<
  701  * Return attributes for the given type.
  702  *
  703  * Requires:
  704  *\li   'rdtype' are known.
  705  *
  706  * Returns:
  707  *\li   a bitmask consisting of the following flags.
  708  */
  709 
  710 /*% only one may exist for a name */
  711 #define DNS_RDATATYPEATTR_SINGLETON 0x00000001U
  712 /*% requires no other data be present */
  713 #define DNS_RDATATYPEATTR_EXCLUSIVE 0x00000002U
  714 /*% Is a meta type */
  715 #define DNS_RDATATYPEATTR_META 0x00000004U
  716 /*% Is a DNSSEC type, like RRSIG or NSEC */
  717 #define DNS_RDATATYPEATTR_DNSSEC 0x00000008U
  718 /*% Is a zone cut authority type */
  719 #define DNS_RDATATYPEATTR_ZONECUTAUTH 0x00000010U
  720 /*% Is reserved (unusable) */
  721 #define DNS_RDATATYPEATTR_RESERVED 0x00000020U
  722 /*% Is an unknown type */
  723 #define DNS_RDATATYPEATTR_UNKNOWN 0x00000040U
  724 /*% Is META, and can only be in a question section */
  725 #define DNS_RDATATYPEATTR_QUESTIONONLY 0x00000080U
  726 /*% Is META, and can NOT be in a question section */
  727 #define DNS_RDATATYPEATTR_NOTQUESTION 0x00000100U
  728 /*% Is present at zone cuts in the parent, not the child */
  729 #define DNS_RDATATYPEATTR_ATPARENT 0x00000200U
  730 /*% Can exist along side a CNAME */
  731 #define DNS_RDATATYPEATTR_ATCNAME 0x00000400U
  732 
  733 dns_rdatatype_t
  734 dns_rdata_covers(dns_rdata_t *rdata);
  735 /*%<
  736  * Return the rdatatype that this type covers.
  737  *
  738  * Requires:
  739  *\li   'rdata' is a valid, non-empty rdata.
  740  *
  741  *\li   'rdata' is a type that covers other rdata types.
  742  *
  743  * Returns:
  744  *\li   The type covered.
  745  */
  746 
  747 bool
  748 dns_rdata_checkowner(const dns_name_t *name, dns_rdataclass_t rdclass,
  749              dns_rdatatype_t type, bool wildcard);
  750 /*
  751  * Returns whether this is a valid ownername for this <type,class>.
  752  * If wildcard is true allow the first label to be a wildcard if
  753  * appropriate.
  754  *
  755  * Requires:
  756  *  'name' is a valid name.
  757  */
  758 
  759 bool
  760 dns_rdata_checknames(dns_rdata_t *rdata, const dns_name_t *owner,
  761              dns_name_t *bad);
  762 /*
  763  * Returns whether 'rdata' contains valid domain names.  The checks are
  764  * sensitive to the owner name.
  765  *
  766  * If 'bad' is non-NULL and a domain name fails the check the
  767  * the offending name will be return in 'bad' by cloning from
  768  * the 'rdata' contents.
  769  *
  770  * Requires:
  771  *  'rdata' to be valid.
  772  *  'owner' to be valid.
  773  *  'bad'   to be NULL or valid.
  774  */
  775 
  776 void
  777 dns_rdata_exists(dns_rdata_t *rdata, dns_rdatatype_t type);
  778 
  779 void
  780 dns_rdata_notexist(dns_rdata_t *rdata, dns_rdatatype_t type);
  781 
  782 void
  783 dns_rdata_deleterrset(dns_rdata_t *rdata, dns_rdatatype_t type);
  784 
  785 void
  786 dns_rdata_makedelete(dns_rdata_t *rdata);
  787 
  788 const char *
  789 dns_rdata_updateop(dns_rdata_t *rdata, dns_section_t section);
  790 
  791 ISC_LANG_ENDDECLS
  792 
  793 #endif /* DNS_RDATA_H */