"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/lib/dns/include/dns/rdata.h" (7 Sep 2020, 21600 Bytes) of package /linux/misc/dns/bind9/9.11.23/bind-9.11.23.tar.gz:


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