"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.11.23/lib/dns/include/dns/message.h" (7 Sep 2020, 39532 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 "message.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_MESSAGE_H
   13 #define DNS_MESSAGE_H 1
   14 
   15 /***
   16  ***    Imports
   17  ***/
   18 
   19 #include <inttypes.h>
   20 #include <stdbool.h>
   21 
   22 #include <isc/lang.h>
   23 #include <isc/magic.h>
   24 
   25 #include <dns/compress.h>
   26 #include <dns/masterdump.h>
   27 #include <dns/types.h>
   28 
   29 #include <dst/dst.h>
   30 
   31 /*! \file dns/message.h
   32  * \brief Message Handling Module
   33  *
   34  * How this beast works:
   35  *
   36  * When a dns message is received in a buffer, dns_message_parse() is called
   37  * on the memory region.  Various items are checked including the format
   38  * of the message (if counts are right, if counts consume the entire sections,
   39  * and if sections consume the entire message) and known pseudo-RRs in the
   40  * additional data section are analyzed and removed.
   41  *
   42  * TSIG checking is also done at this layer, and any DNSSEC transaction
   43  * signatures should also be checked here.
   44  *
   45  * Notes on using the gettemp*() and puttemp*() functions:
   46  *
   47  * These functions return items (names, rdatasets, etc) allocated from some
   48  * internal state of the dns_message_t.
   49  *
   50  * Names and rdatasets must be put back into the dns_message_t in
   51  * one of two ways.  Assume a name was allocated via
   52  * dns_message_gettempname():
   53  *
   54  *\li   (1) insert it into a section, using dns_message_addname().
   55  *
   56  *\li   (2) return it to the message using dns_message_puttempname().
   57  *
   58  * The same applies to rdatasets.
   59  *
   60  * On the other hand, offsets, rdatalists and rdatas allocated using
   61  * dns_message_gettemp*() will always be freed automatically
   62  * when the message is reset or destroyed; calling dns_message_puttemp*()
   63  * on rdatalists and rdatas is optional and serves only to enable the item
   64  * to be reused multiple times during the lifetime of the message; offsets
   65  * cannot be reused.
   66  *
   67  * Buffers allocated using isc_buffer_allocate() can be automatically freed
   68  * as well by giving the buffer to the message using dns_message_takebuffer().
   69  * Doing this will cause the buffer to be freed using isc_buffer_free()
   70  * when the section lists are cleared, such as in a reset or in a destroy.
   71  * Since the buffer itself exists until the message is destroyed, this sort
   72  * of code can be written:
   73  *
   74  * \code
   75  *  buffer = isc_buffer_allocate(mctx, 512);
   76  *  name = NULL;
   77  *  name = dns_message_gettempname(message, &name);
   78  *  dns_name_init(name, NULL);
   79  *  result = dns_name_fromtext(name, &source, dns_rootname, 0, buffer);
   80  *  dns_message_takebuffer(message, &buffer);
   81  * \endcode
   82  *
   83  *
   84  * TODO:
   85  *
   86  * XXX Needed:  ways to set and retrieve EDNS information, add rdata to a
   87  * section, move rdata from one section to another, remove rdata, etc.
   88  */
   89 
   90 #define DNS_MESSAGEFLAG_QR      0x8000U
   91 #define DNS_MESSAGEFLAG_AA      0x0400U
   92 #define DNS_MESSAGEFLAG_TC      0x0200U
   93 #define DNS_MESSAGEFLAG_RD      0x0100U
   94 #define DNS_MESSAGEFLAG_RA      0x0080U
   95 #define DNS_MESSAGEFLAG_AD      0x0020U
   96 #define DNS_MESSAGEFLAG_CD      0x0010U
   97 
   98 /*%< EDNS0 extended message flags */
   99 #define DNS_MESSAGEEXTFLAG_DO       0x8000U
  100 
  101 /*%< EDNS0 extended OPT codes */
  102 #define DNS_OPT_LLQ       1  /*%< LLQ opt code */
  103 #define DNS_OPT_NSID          3  /*%< NSID opt code */
  104 #define DNS_OPT_CLIENT_SUBNET 8  /*%< client subnet opt code */
  105 #define DNS_OPT_EXPIRE        9  /*%< EXPIRE opt code */
  106 #define DNS_OPT_COOKIE        10 /*%< COOKIE opt code */
  107 #define DNS_OPT_TCP_KEEPALIVE 11 /*%< TCP keepalive opt code */
  108 #define DNS_OPT_PAD       12 /*%< PAD opt code */
  109 #define DNS_OPT_KEY_TAG       14 /*%< Key tag opt code */
  110 #define DNS_OPT_EDE       15 /*%< Extended DNS Error opt code */
  111 #define DNS_OPT_CLIENT_TAG    16 /*%< Client tag opt code */
  112 #define DNS_OPT_SERVER_TAG    17 /*%< Server tag opt code */
  113 
  114 /*%< Experimental options [65001...65534] as per RFC6891 */
  115 
  116 /*%< The number of EDNS options we know about. */
  117 #define DNS_EDNSOPTIONS 5
  118 
  119 #define DNS_MESSAGE_REPLYPRESERVE   (DNS_MESSAGEFLAG_RD|DNS_MESSAGEFLAG_CD)
  120 #define DNS_MESSAGEEXTFLAG_REPLYPRESERVE (DNS_MESSAGEEXTFLAG_DO)
  121 
  122 #define DNS_MESSAGE_HEADERLEN       12 /*%< 6 uint16_t's */
  123 
  124 #define DNS_MESSAGE_MAGIC       ISC_MAGIC('M','S','G','@')
  125 #define DNS_MESSAGE_VALID(msg)      ISC_MAGIC_VALID(msg, DNS_MESSAGE_MAGIC)
  126 
  127 /*
  128  * Ordering here matters.  DNS_SECTION_ANY must be the lowest and negative,
  129  * and DNS_SECTION_MAX must be one greater than the last used section.
  130  */
  131 typedef int dns_section_t;
  132 #define DNS_SECTION_ANY         (-1)
  133 #define DNS_SECTION_QUESTION        0
  134 #define DNS_SECTION_ANSWER      1
  135 #define DNS_SECTION_AUTHORITY       2
  136 #define DNS_SECTION_ADDITIONAL      3
  137 #define DNS_SECTION_MAX         4
  138 
  139 typedef int dns_pseudosection_t;
  140 #define DNS_PSEUDOSECTION_ANY       (-1)
  141 #define DNS_PSEUDOSECTION_OPT           0
  142 #define DNS_PSEUDOSECTION_TSIG          1
  143 #define DNS_PSEUDOSECTION_SIG0          2
  144 #define DNS_PSEUDOSECTION_MAX           3
  145 
  146 typedef int dns_messagetextflag_t;
  147 #define DNS_MESSAGETEXTFLAG_NOCOMMENTS  0x0001
  148 #define DNS_MESSAGETEXTFLAG_NOHEADERS   0x0002
  149 #define DNS_MESSAGETEXTFLAG_ONESOA  0x0004
  150 #define DNS_MESSAGETEXTFLAG_OMITSOA 0x0008
  151 
  152 /*
  153  * Dynamic update names for these sections.
  154  */
  155 #define DNS_SECTION_ZONE        DNS_SECTION_QUESTION
  156 #define DNS_SECTION_PREREQUISITE    DNS_SECTION_ANSWER
  157 #define DNS_SECTION_UPDATE      DNS_SECTION_AUTHORITY
  158 
  159 /*
  160  * These tell the message library how the created dns_message_t will be used.
  161  */
  162 #define DNS_MESSAGE_INTENTUNKNOWN   0 /*%< internal use only */
  163 #define DNS_MESSAGE_INTENTPARSE     1 /*%< parsing messages */
  164 #define DNS_MESSAGE_INTENTRENDER    2 /*%< rendering */
  165 
  166 /*
  167  * Control behavior of parsing
  168  */
  169 #define DNS_MESSAGEPARSE_PRESERVEORDER  0x0001  /*%< preserve rdata order */
  170 #define DNS_MESSAGEPARSE_BESTEFFORT 0x0002  /*%< return a message if a
  171                            recoverable parse error
  172                            occurs */
  173 #define DNS_MESSAGEPARSE_CLONEBUFFER    0x0004  /*%< save a copy of the
  174                            source buffer */
  175 #define DNS_MESSAGEPARSE_IGNORETRUNCATION 0x0008 /*%< truncation errors are
  176                           * not fatal. */
  177 
  178 /*
  179  * Control behavior of rendering
  180  */
  181 #define DNS_MESSAGERENDER_ORDERED   0x0001  /*%< don't change order */
  182 #define DNS_MESSAGERENDER_PARTIAL   0x0002  /*%< allow a partial rdataset */
  183 #define DNS_MESSAGERENDER_OMITDNSSEC    0x0004  /*%< omit DNSSEC records */
  184 #define DNS_MESSAGERENDER_PREFER_A  0x0008  /*%< prefer A records in
  185                              additional section. */
  186 #define DNS_MESSAGERENDER_PREFER_AAAA   0x0010  /*%< prefer AAAA records in
  187                           additional section. */
  188 #ifdef ALLOW_FILTER_AAAA
  189 #define DNS_MESSAGERENDER_FILTER_AAAA   0x0020  /*%< filter AAAA records */
  190 #endif
  191 
  192 typedef struct dns_msgblock dns_msgblock_t;
  193 
  194 struct dns_message {
  195     /* public from here down */
  196     unsigned int            magic;
  197 
  198     dns_messageid_t         id;
  199     unsigned int            flags;
  200     dns_rcode_t         rcode;
  201     dns_opcode_t            opcode;
  202     dns_rdataclass_t        rdclass;
  203 
  204     /* 4 real, 1 pseudo */
  205     unsigned int            counts[DNS_SECTION_MAX];
  206 
  207     /* private from here down */
  208     dns_namelist_t          sections[DNS_SECTION_MAX];
  209     dns_name_t             *cursors[DNS_SECTION_MAX];
  210     dns_rdataset_t             *opt;
  211     dns_rdataset_t             *sig0;
  212     dns_rdataset_t             *tsig;
  213 
  214     int             state;
  215     unsigned int            from_to_wire : 2;
  216     unsigned int            header_ok : 1;
  217     unsigned int            question_ok : 1;
  218     unsigned int            tcp_continuation : 1;
  219     unsigned int            verified_sig : 1;
  220     unsigned int            verify_attempted : 1;
  221     unsigned int            free_query : 1;
  222     unsigned int            free_saved : 1;
  223     unsigned int            cc_ok : 1;
  224     unsigned int            cc_bad : 1;
  225     unsigned int            tkey : 1;
  226     unsigned int            rdclass_set : 1;
  227 
  228     unsigned int            opt_reserved;
  229     unsigned int            sig_reserved;
  230     unsigned int            reserved; /* reserved space (render) */
  231 
  232     isc_buffer_t               *buffer;
  233     dns_compress_t             *cctx;
  234 
  235     isc_mem_t              *mctx;
  236     isc_mempool_t              *namepool;
  237     isc_mempool_t              *rdspool;
  238 
  239     isc_bufferlist_t        scratchpad;
  240     isc_bufferlist_t        cleanup;
  241 
  242     ISC_LIST(dns_msgblock_t)    rdatas;
  243     ISC_LIST(dns_msgblock_t)    rdatalists;
  244     ISC_LIST(dns_msgblock_t)    offsets;
  245 
  246     ISC_LIST(dns_rdata_t)       freerdata;
  247     ISC_LIST(dns_rdatalist_t)   freerdatalist;
  248 
  249     dns_rcode_t         tsigstatus;
  250     dns_rcode_t         querytsigstatus;
  251     dns_name_t             *tsigname; /* Owner name of TSIG, if any */
  252     dns_rdataset_t             *querytsig;
  253     dns_tsigkey_t              *tsigkey;
  254     dst_context_t              *tsigctx;
  255     int             sigstart;
  256     int             timeadjust;
  257 
  258     dns_name_t             *sig0name; /* Owner name of SIG0, if any */
  259     dst_key_t              *sig0key;
  260     dns_rcode_t         sig0status;
  261     isc_region_t            query;
  262     isc_region_t            saved;
  263 
  264     dns_rdatasetorderfunc_t     order;
  265     const void *            order_arg;
  266 };
  267 
  268 struct dns_ednsopt {
  269     uint16_t            code;
  270     uint16_t            length;
  271     unsigned char           *value;
  272 };
  273 
  274 /***
  275  *** Functions
  276  ***/
  277 
  278 ISC_LANG_BEGINDECLS
  279 
  280 isc_result_t
  281 dns_message_create(isc_mem_t *mctx, unsigned int intent, dns_message_t **msgp);
  282 
  283 /*%<
  284  * Create msg structure.
  285  *
  286  * This function will allocate some internal blocks of memory that are
  287  * expected to be needed for parsing or rendering nearly any type of message.
  288  *
  289  * Requires:
  290  *\li   'mctx' be a valid memory context.
  291  *
  292  *\li   'msgp' be non-null and '*msg' be NULL.
  293  *
  294  *\li   'intent' must be one of DNS_MESSAGE_INTENTPARSE or
  295  *  #DNS_MESSAGE_INTENTRENDER.
  296  *
  297  * Ensures:
  298  *\li   The data in "*msg" is set to indicate an unused and empty msg
  299  *  structure.
  300  *
  301  * Returns:
  302  *\li   #ISC_R_NOMEMORY     -- out of memory
  303  *\li   #ISC_R_SUCCESS      -- success
  304  */
  305 
  306 void
  307 dns_message_reset(dns_message_t *msg, unsigned int intent);
  308 /*%<
  309  * Reset a message structure to default state.  All internal lists are freed
  310  * or reset to a default state as well.  This is simply a more efficient
  311  * way to call dns_message_destroy() followed by dns_message_allocate(),
  312  * since it avoid many memory allocations.
  313  *
  314  * If any data loanouts (buffers, names, rdatas, etc) were requested,
  315  * the caller must no longer use them after this call.
  316  *
  317  * The intended next use of the message will be 'intent'.
  318  *
  319  * Requires:
  320  *
  321  *\li   'msg' be valid.
  322  *
  323  *\li   'intent' is DNS_MESSAGE_INTENTPARSE or DNS_MESSAGE_INTENTRENDER
  324  */
  325 
  326 void
  327 dns_message_destroy(dns_message_t **msgp);
  328 /*%<
  329  * Destroy all state in the message.
  330  *
  331  * Requires:
  332  *
  333  *\li   'msgp' be valid.
  334  *
  335  * Ensures:
  336  *\li   '*msgp' == NULL
  337  */
  338 
  339 isc_result_t
  340 dns_message_sectiontotext(dns_message_t *msg, dns_section_t section,
  341               const dns_master_style_t *style,
  342               dns_messagetextflag_t flags,
  343               isc_buffer_t *target);
  344 
  345 isc_result_t
  346 dns_message_pseudosectiontotext(dns_message_t *msg,
  347                 dns_pseudosection_t section,
  348                 const dns_master_style_t *style,
  349                 dns_messagetextflag_t flags,
  350                 isc_buffer_t *target);
  351 /*%<
  352  * Convert section 'section' or 'pseudosection' of message 'msg' to
  353  * a cleartext representation
  354  *
  355  * Notes:
  356  *     \li See dns_message_totext for meanings of flags.
  357  *
  358  * Requires:
  359  *
  360  *\li   'msg' is a valid message.
  361  *
  362  *\li   'style' is a valid master dump style.
  363  *
  364  *\li   'target' is a valid buffer.
  365  *
  366  *\li   'section' is a valid section label.
  367  *
  368  * Ensures:
  369  *
  370  *\li   If the result is success:
  371  *      The used space in 'target' is updated.
  372  *
  373  * Returns:
  374  *
  375  *\li   #ISC_R_SUCCESS
  376  *\li   #ISC_R_NOSPACE
  377  *\li   #ISC_R_NOMORE
  378  *
  379  *\li   Note: On error return, *target may be partially filled with data.
  380 */
  381 
  382 isc_result_t
  383 dns_message_totext(dns_message_t *msg, const dns_master_style_t *style,
  384            dns_messagetextflag_t flags, isc_buffer_t *target);
  385 /*%<
  386  * Convert all sections of message 'msg' to a cleartext representation
  387  *
  388  * Notes on flags:
  389  *\li   If #DNS_MESSAGETEXTFLAG_NOCOMMENTS is cleared, lines beginning with
  390  *  ";;" will be emitted indicating section name.
  391  *\li   If #DNS_MESSAGETEXTFLAG_NOHEADERS is cleared, header lines will be
  392  *  emitted.
  393  *\li   If #DNS_MESSAGETEXTFLAG_ONESOA is set then only print the first
  394  *  SOA record in the answer section.
  395  *\li   If *#DNS_MESSAGETEXTFLAG_OMITSOA is set don't print any SOA records
  396  *  in the answer section.
  397  *
  398  * The SOA flags are useful for suppressing the display of the second
  399  * SOA record in an AXFR by setting #DNS_MESSAGETEXTFLAG_ONESOA on the
  400  * first message in an AXFR stream and #DNS_MESSAGETEXTFLAG_OMITSOA on
  401  * subsequent messages.
  402  *
  403  * Requires:
  404  *
  405  *\li   'msg' is a valid message.
  406  *
  407  *\li   'style' is a valid master dump style.
  408  *
  409  *\li   'target' is a valid buffer.
  410  *
  411  * Ensures:
  412  *
  413  *\li   If the result is success:
  414  *      The used space in 'target' is updated.
  415  *
  416  * Returns:
  417  *
  418  *\li   #ISC_R_SUCCESS
  419  *\li   #ISC_R_NOSPACE
  420  *\li   #ISC_R_NOMORE
  421  *
  422  *\li   Note: On error return, *target may be partially filled with data.
  423  */
  424 
  425 isc_result_t
  426 dns_message_parse(dns_message_t *msg, isc_buffer_t *source,
  427           unsigned int options);
  428 /*%<
  429  * Parse raw wire data in 'source' as a DNS message.
  430  *
  431  * OPT records are detected and stored in the pseudo-section "opt".
  432  * TSIGs are detected and stored in the pseudo-section "tsig".
  433  *
  434  * If #DNS_MESSAGEPARSE_PRESERVEORDER is set, or if the opcode of the message
  435  * is UPDATE, a separate dns_name_t object will be created for each RR in the
  436  * message.  Each such dns_name_t will have a single rdataset containing the
  437  * single RR, and the order of the RRs in the message is preserved.
  438  * Otherwise, only one dns_name_t object will be created for each unique
  439  * owner name in the section, and each such dns_name_t will have a list
  440  * of rdatasets.  To access the names and their data, use
  441  * dns_message_firstname() and dns_message_nextname().
  442  *
  443  * If #DNS_MESSAGEPARSE_BESTEFFORT is set, errors in message content will
  444  * not be considered FORMERRs.  If the entire message can be parsed, it
  445  * will be returned and DNS_R_RECOVERABLE will be returned.
  446  *
  447  * If #DNS_MESSAGEPARSE_IGNORETRUNCATION is set then return as many complete
  448  * RR's as possible, DNS_R_RECOVERABLE will be returned.
  449  *
  450  * OPT and TSIG records are always handled specially, regardless of the
  451  * 'preserve_order' setting.
  452  *
  453  * Requires:
  454  *\li   "msg" be valid.
  455  *
  456  *\li   "buffer" be a wire format buffer.
  457  *
  458  * Ensures:
  459  *\li   The buffer's data format is correct.
  460  *
  461  *\li   The buffer's contents verify as correct regarding header bits, buffer
  462  *  and rdata sizes, etc.
  463  *
  464  * Returns:
  465  *\li   #ISC_R_SUCCESS      -- all is well
  466  *\li   #ISC_R_NOMEMORY     -- no memory
  467  *\li   #DNS_R_RECOVERABLE  -- the message parsed properly, but contained
  468  *                 errors.
  469  *\li   Many other errors possible XXXMLG
  470  */
  471 
  472 isc_result_t
  473 dns_message_renderbegin(dns_message_t *msg, dns_compress_t *cctx,
  474             isc_buffer_t *buffer);
  475 /*%<
  476  * Begin rendering on a message.  Only one call can be made to this function
  477  * per message.
  478  *
  479  * The compression context is "owned" by the message library until
  480  * dns_message_renderend() is called.  It must be invalidated by the caller.
  481  *
  482  * The buffer is "owned" by the message library until dns_message_renderend()
  483  * is called.
  484  *
  485  * Requires:
  486  *
  487  *\li   'msg' be valid.
  488  *
  489  *\li   'cctx' be valid.
  490  *
  491  *\li   'buffer' is a valid buffer.
  492  *
  493  * Side Effects:
  494  *
  495  *\li   The buffer is cleared before it is used.
  496  *
  497  * Returns:
  498  *\li   #ISC_R_SUCCESS      -- all is well
  499  *\li   #ISC_R_NOSPACE      -- output buffer is too small
  500  */
  501 
  502 isc_result_t
  503 dns_message_renderchangebuffer(dns_message_t *msg, isc_buffer_t *buffer);
  504 /*%<
  505  * Reset the buffer.  This can be used after growing the old buffer
  506  * on a ISC_R_NOSPACE return from most of the render functions.
  507  *
  508  * On successful completion, the old buffer is no longer used by the
  509  * library.  The new buffer is owned by the library until
  510  * dns_message_renderend() is called.
  511  *
  512  * Requires:
  513  *
  514  *\li   'msg' be valid.
  515  *
  516  *\li   dns_message_renderbegin() was called.
  517  *
  518  *\li   buffer != NULL.
  519  *
  520  * Returns:
  521  *\li   #ISC_R_NOSPACE      -- new buffer is too small
  522  *\li   #ISC_R_SUCCESS      -- all is well.
  523  */
  524 
  525 isc_result_t
  526 dns_message_renderreserve(dns_message_t *msg, unsigned int space);
  527 /*%<
  528  * XXXMLG should use size_t rather than unsigned int once the buffer
  529  * API is cleaned up
  530  *
  531  * Reserve "space" bytes in the given buffer.
  532  *
  533  * Requires:
  534  *
  535  *\li   'msg' be valid.
  536  *
  537  *\li   dns_message_renderbegin() was called.
  538  *
  539  * Returns:
  540  *\li   #ISC_R_SUCCESS      -- all is well.
  541  *\li   #ISC_R_NOSPACE      -- not enough free space in the buffer.
  542  */
  543 
  544 void
  545 dns_message_renderrelease(dns_message_t *msg, unsigned int space);
  546 /*%<
  547  * XXXMLG should use size_t rather than unsigned int once the buffer
  548  * API is cleaned up
  549  *
  550  * Release "space" bytes in the given buffer that was previously reserved.
  551  *
  552  * Requires:
  553  *
  554  *\li   'msg' be valid.
  555  *
  556  *\li   'space' is less than or equal to the total amount of space reserved
  557  *  via prior calls to dns_message_renderreserve().
  558  *
  559  *\li   dns_message_renderbegin() was called.
  560  */
  561 
  562 isc_result_t
  563 dns_message_rendersection(dns_message_t *msg, dns_section_t section,
  564               unsigned int options);
  565 /*%<
  566  * Render all names, rdatalists, etc from the given section at the
  567  * specified priority or higher.
  568  *
  569  * Requires:
  570  *\li   'msg' be valid.
  571  *
  572  *\li   'section' be a valid section.
  573  *
  574  *\li   dns_message_renderbegin() was called.
  575  *
  576  * Returns:
  577  *\li   #ISC_R_SUCCESS      -- all records were written, and there are
  578  *                 no more records for this section.
  579  *\li   #ISC_R_NOSPACE      -- Not enough room in the buffer to write
  580  *                 all records requested.
  581  *\li   #DNS_R_MOREDATA     -- All requested records written, and there
  582  *                 are records remaining for this section.
  583  */
  584 
  585 void
  586 dns_message_renderheader(dns_message_t *msg, isc_buffer_t *target);
  587 /*%<
  588  * Render the message header.  This is implicitly called by
  589  * dns_message_renderend().
  590  *
  591  * Requires:
  592  *
  593  *\li   'msg' be a valid message.
  594  *
  595  *\li   dns_message_renderbegin() was called.
  596  *
  597  *\li   'target' is a valid buffer with enough space to hold a message header
  598  */
  599 
  600 isc_result_t
  601 dns_message_renderend(dns_message_t *msg);
  602 /*%<
  603  * Finish rendering to the buffer.  Note that more data can be in the
  604  * 'msg' structure.  Destroying the structure will free this, or in a multi-
  605  * part EDNS1 message this data can be rendered to another buffer later.
  606  *
  607  * Requires:
  608  *
  609  *\li   'msg' be a valid message.
  610  *
  611  *\li   dns_message_renderbegin() was called.
  612  *
  613  * Returns:
  614  *\li   #ISC_R_SUCCESS      -- all is well.
  615  */
  616 
  617 void
  618 dns_message_renderreset(dns_message_t *msg);
  619 /*%<
  620  * Reset the message so that it may be rendered again.
  621  *
  622  * Notes:
  623  *
  624  *\li   If dns_message_renderbegin() has been called, dns_message_renderend()
  625  *  must be called before calling this function.
  626  *
  627  * Requires:
  628  *
  629  *\li   'msg' be a valid message with rendering intent.
  630  */
  631 
  632 isc_result_t
  633 dns_message_firstname(dns_message_t *msg, dns_section_t section);
  634 /*%<
  635  * Set internal per-section name pointer to the beginning of the section.
  636  *
  637  * The functions dns_message_firstname() and dns_message_nextname() may
  638  * be used for iterating over the owner names in a section.
  639  *
  640  * Requires:
  641  *
  642  *\li       'msg' be valid.
  643  *
  644  *\li   'section' be a valid section.
  645  *
  646  * Returns:
  647  *\li   #ISC_R_SUCCESS      -- All is well.
  648  *\li   #ISC_R_NOMORE       -- No names on given section.
  649  */
  650 
  651 isc_result_t
  652 dns_message_nextname(dns_message_t *msg, dns_section_t section);
  653 /*%<
  654  * Sets the internal per-section name pointer to point to the next name
  655  * in that section.
  656  *
  657  * Requires:
  658  *
  659  * \li      'msg' be valid.
  660  *
  661  *\li   'section' be a valid section.
  662  *
  663  *\li   dns_message_firstname() must have been called on this section,
  664  *  and the result was ISC_R_SUCCESS.
  665  *
  666  * Returns:
  667  *\li   #ISC_R_SUCCESS      -- All is well.
  668  *\li   #ISC_R_NOMORE       -- No more names in given section.
  669  */
  670 
  671 void
  672 dns_message_currentname(dns_message_t *msg, dns_section_t section,
  673             dns_name_t **name);
  674 /*%<
  675  * Sets 'name' to point to the name where the per-section internal name
  676  * pointer is currently set.
  677  *
  678  * This function returns the name in the database, so any data associated
  679  * with it (via the name's "list" member) contains the actual rdatasets.
  680  *
  681  * Requires:
  682  *
  683  *\li   'msg' be valid.
  684  *
  685  *\li   'name' be non-NULL, and *name be NULL.
  686  *
  687  *\li   'section' be a valid section.
  688  *
  689  *\li   dns_message_firstname() must have been called on this section,
  690  *  and the result of it and any dns_message_nextname() calls was
  691  *  #ISC_R_SUCCESS.
  692  */
  693 
  694 isc_result_t
  695 dns_message_findname(dns_message_t *msg, dns_section_t section,
  696              dns_name_t *target, dns_rdatatype_t type,
  697              dns_rdatatype_t covers, dns_name_t **foundname,
  698              dns_rdataset_t **rdataset);
  699 /*%<
  700  * Search for a name in the specified section.  If it is found, *name is
  701  * set to point to the name, and *rdataset is set to point to the found
  702  * rdataset (if type is specified as other than dns_rdatatype_any).
  703  *
  704  * Requires:
  705  *\li   'msg' be valid.
  706  *
  707  *\li   'section' be a valid section.
  708  *
  709  *\li   If a pointer to the name is desired, 'foundname' should be non-NULL.
  710  *  If it is non-NULL, '*foundname' MUST be NULL.
  711  *
  712  *\li   If a type other than dns_datatype_any is searched for, 'rdataset'
  713  *  may be non-NULL, '*rdataset' be NULL, and will point at the found
  714  *  rdataset.  If the type is dns_datatype_any, 'rdataset' must be NULL.
  715  *
  716  *\li   'target' be a valid name.
  717  *
  718  *\li   'type' be a valid type.
  719  *
  720  *\li   If 'type' is dns_rdatatype_rrsig, 'covers' must be a valid type.
  721  *  Otherwise it should be 0.
  722  *
  723  * Returns:
  724  *\li   #ISC_R_SUCCESS      -- all is well.
  725  *\li   #DNS_R_NXDOMAIN     -- name does not exist in that section.
  726  *\li   #DNS_R_NXRRSET      -- The name does exist, but the desired
  727  *                 type does not.
  728  */
  729 
  730 isc_result_t
  731 dns_message_findtype(dns_name_t *name, dns_rdatatype_t type,
  732              dns_rdatatype_t covers, dns_rdataset_t **rdataset);
  733 /*%<
  734  * Search the name for the specified type.  If it is found, *rdataset is
  735  * filled in with a pointer to that rdataset.
  736  *
  737  * Requires:
  738  *\li   if '**rdataset' is non-NULL, *rdataset needs to be NULL.
  739  *
  740  *\li   'type' be a valid type, and NOT dns_rdatatype_any.
  741  *
  742  *\li   If 'type' is dns_rdatatype_rrsig, 'covers' must be a valid type.
  743  *  Otherwise it should be 0.
  744  *
  745  * Returns:
  746  *\li   #ISC_R_SUCCESS      -- all is well.
  747  *\li   #ISC_R_NOTFOUND     -- the desired type does not exist.
  748  */
  749 
  750 isc_result_t
  751 dns_message_find(dns_name_t *name, dns_rdataclass_t rdclass,
  752          dns_rdatatype_t type, dns_rdatatype_t covers,
  753          dns_rdataset_t **rdataset);
  754 /*%<
  755  * Search the name for the specified rdclass and type.  If it is found,
  756  * *rdataset is filled in with a pointer to that rdataset.
  757  *
  758  * Requires:
  759  *\li   if '**rdataset' is non-NULL, *rdataset needs to be NULL.
  760  *
  761  *\li   'type' be a valid type, and NOT dns_rdatatype_any.
  762  *
  763  *\li   If 'type' is dns_rdatatype_rrsig, 'covers' must be a valid type.
  764  *  Otherwise it should be 0.
  765  *
  766  * Returns:
  767  *\li   #ISC_R_SUCCESS      -- all is well.
  768  *\li   #ISC_R_NOTFOUND     -- the desired type does not exist.
  769  */
  770 
  771 void
  772 dns_message_movename(dns_message_t *msg, dns_name_t *name,
  773              dns_section_t fromsection,
  774              dns_section_t tosection);
  775 /*%<
  776  * Move a name from one section to another.
  777  *
  778  * Requires:
  779  *
  780  *\li   'msg' be valid.
  781  *
  782  *\li   'name' must be a name already in 'fromsection'.
  783  *
  784  *\li   'fromsection' must be a valid section.
  785  *
  786  *\li   'tosection' must be a valid section.
  787  */
  788 
  789 void
  790 dns_message_addname(dns_message_t *msg, dns_name_t *name,
  791             dns_section_t section);
  792 /*%<
  793  * Adds the name to the given section.
  794  *
  795  * It is the caller's responsibility to enforce any unique name requirements
  796  * in a section.
  797  *
  798  * Requires:
  799  *
  800  *\li   'msg' be valid, and be a renderable message.
  801  *
  802  *\li   'name' be a valid absolute name.
  803  *
  804  *\li   'section' be a named section.
  805  */
  806 
  807 void
  808 dns_message_removename(dns_message_t *msg, dns_name_t *name,
  809                dns_section_t section);
  810 /*%<
  811  * Remove a existing name from a given section.
  812  *
  813  * It is the caller's responsibility to ensure the name is part of the
  814  * given section.
  815  *
  816  * Requires:
  817  *
  818  *\li   'msg' be valid, and be a renderable message.
  819  *
  820  *\li   'name' be a valid absolute name.
  821  *
  822  *\li   'section' be a named section.
  823  */
  824 
  825 
  826 /*
  827  * LOANOUT FUNCTIONS
  828  *
  829  * Each of these functions loan a particular type of data to the caller.
  830  * The storage for these will vanish when the message is destroyed or
  831  * reset, and must NOT be used after these operations.
  832  */
  833 
  834 isc_result_t
  835 dns_message_gettempname(dns_message_t *msg, dns_name_t **item);
  836 /*%<
  837  * Return a name that can be used for any temporary purpose, including
  838  * inserting into the message's linked lists.  The name must be returned
  839  * to the message code using dns_message_puttempname() or inserted into
  840  * one of the message's sections before the message is destroyed.
  841  *
  842  * It is the caller's responsibility to initialize this name.
  843  *
  844  * Requires:
  845  *\li   msg be a valid message
  846  *
  847  *\li   item != NULL && *item == NULL
  848  *
  849  * Returns:
  850  *\li   #ISC_R_SUCCESS      -- All is well.
  851  *\li   #ISC_R_NOMEMORY     -- No item can be allocated.
  852  */
  853 
  854 isc_result_t
  855 dns_message_gettempoffsets(dns_message_t *msg, dns_offsets_t **item);
  856 /*%<
  857  * Return an offsets array that can be used for any temporary purpose,
  858  * such as attaching to a temporary name.  The offsets will be freed
  859  * when the message is destroyed or reset.
  860  *
  861  * Requires:
  862  *\li   msg be a valid message
  863  *
  864  *\li   item != NULL && *item == NULL
  865  *
  866  * Returns:
  867  *\li   #ISC_R_SUCCESS      -- All is well.
  868  *\li   #ISC_R_NOMEMORY     -- No item can be allocated.
  869  */
  870 
  871 isc_result_t
  872 dns_message_gettemprdata(dns_message_t *msg, dns_rdata_t **item);
  873 /*%<
  874  * Return a rdata that can be used for any temporary purpose, including
  875  * inserting into the message's linked lists.  The rdata will be freed
  876  * when the message is destroyed or reset.
  877  *
  878  * Requires:
  879  *\li   msg be a valid message
  880  *
  881  *\li   item != NULL && *item == NULL
  882  *
  883  * Returns:
  884  *\li   #ISC_R_SUCCESS      -- All is well.
  885  *\li   #ISC_R_NOMEMORY     -- No item can be allocated.
  886  */
  887 
  888 isc_result_t
  889 dns_message_gettemprdataset(dns_message_t *msg, dns_rdataset_t **item);
  890 /*%<
  891  * Return a rdataset that can be used for any temporary purpose, including
  892  * inserting into the message's linked lists. The name must be returned
  893  * to the message code using dns_message_puttempname() or inserted into
  894  * one of the message's sections before the message is destroyed.
  895  *
  896  * Requires:
  897  *\li   msg be a valid message
  898  *
  899  *\li   item != NULL && *item == NULL
  900  *
  901  * Returns:
  902  *\li   #ISC_R_SUCCESS      -- All is well.
  903  *\li   #ISC_R_NOMEMORY     -- No item can be allocated.
  904  */
  905 
  906 isc_result_t
  907 dns_message_gettemprdatalist(dns_message_t *msg, dns_rdatalist_t **item);
  908 /*%<
  909  * Return a rdatalist that can be used for any temporary purpose, including
  910  * inserting into the message's linked lists.  The rdatalist will be
  911  * destroyed when the message is destroyed or reset.
  912  *
  913  * Requires:
  914  *\li   msg be a valid message
  915  *
  916  *\li   item != NULL && *item == NULL
  917  *
  918  * Returns:
  919  *\li   #ISC_R_SUCCESS      -- All is well.
  920  *\li   #ISC_R_NOMEMORY     -- No item can be allocated.
  921  */
  922 
  923 void
  924 dns_message_puttempname(dns_message_t *msg, dns_name_t **item);
  925 /*%<
  926  * Return a borrowed name to the message's name free list.
  927  *
  928  * Requires:
  929  *\li   msg be a valid message
  930  *
  931  *\li   item != NULL && *item point to a name returned by
  932  *  dns_message_gettempname()
  933  *
  934  * Ensures:
  935  *\li   *item == NULL
  936  */
  937 
  938 void
  939 dns_message_puttemprdata(dns_message_t *msg, dns_rdata_t **item);
  940 /*%<
  941  * Return a borrowed rdata to the message's rdata free list.
  942  *
  943  * Requires:
  944  *\li   msg be a valid message
  945  *
  946  *\li   item != NULL && *item point to a rdata returned by
  947  *  dns_message_gettemprdata()
  948  *
  949  * Ensures:
  950  *\li   *item == NULL
  951  */
  952 
  953 void
  954 dns_message_puttemprdataset(dns_message_t *msg, dns_rdataset_t **item);
  955 /*%<
  956  * Return a borrowed rdataset to the message's rdataset free list.
  957  *
  958  * Requires:
  959  *\li   msg be a valid message
  960  *
  961  *\li   item != NULL && *item point to a rdataset returned by
  962  *  dns_message_gettemprdataset()
  963  *
  964  * Ensures:
  965  *\li   *item == NULL
  966  */
  967 
  968 void
  969 dns_message_puttemprdatalist(dns_message_t *msg, dns_rdatalist_t **item);
  970 /*%<
  971  * Return a borrowed rdatalist to the message's rdatalist free list.
  972  *
  973  * Requires:
  974  *\li   msg be a valid message
  975  *
  976  *\li   item != NULL && *item point to a rdatalist returned by
  977  *  dns_message_gettemprdatalist()
  978  *
  979  * Ensures:
  980  *\li   *item == NULL
  981  */
  982 
  983 isc_result_t
  984 dns_message_peekheader(isc_buffer_t *source, dns_messageid_t *idp,
  985                unsigned int *flagsp);
  986 /*%<
  987  * Assume the remaining region of "source" is a DNS message.  Peek into
  988  * it and fill in "*idp" with the message id, and "*flagsp" with the flags.
  989  *
  990  * Requires:
  991  *
  992  *\li   source != NULL
  993  *
  994  * Ensures:
  995  *
  996  *\li   if (idp != NULL) *idp == message id.
  997  *
  998  *\li   if (flagsp != NULL) *flagsp == message flags.
  999  *
 1000  * Returns:
 1001  *
 1002  *\li   #ISC_R_SUCCESS      -- all is well.
 1003  *
 1004  *\li   #ISC_R_UNEXPECTEDEND    -- buffer doesn't contain enough for a header.
 1005  */
 1006 
 1007 isc_result_t
 1008 dns_message_reply(dns_message_t *msg, bool want_question_section);
 1009 /*%<
 1010  * Start formatting a reply to the query in 'msg'.
 1011  *
 1012  * Requires:
 1013  *
 1014  *\li   'msg' is a valid message with parsing intent, and contains a query.
 1015  *
 1016  * Ensures:
 1017  *
 1018  *\li   The message will have a rendering intent.  If 'want_question_section'
 1019  *  is true, the message opcode is query or notify, and the question
 1020  *  section is present and properly formatted, then the question section
 1021  *  will be included in the reply.  All other sections will be cleared.
 1022  *  The QR flag will be set, the RD flag will be preserved, and all other
 1023  *  flags will be cleared.
 1024  *
 1025  * Returns:
 1026  *
 1027  *\li   #ISC_R_SUCCESS      -- all is well.
 1028  *
 1029  *\li   #DNS_R_FORMERR      -- the header or question section of the
 1030  *                 message is invalid, replying is impossible.
 1031  *                 If DNS_R_FORMERR is returned when
 1032  *                 want_question_section is false, then
 1033  *                 it's the header section that's bad;
 1034  *                 otherwise either of the header or question
 1035  *                 sections may be bad.
 1036  */
 1037 
 1038 dns_rdataset_t *
 1039 dns_message_getopt(dns_message_t *msg);
 1040 /*%<
 1041  * Get the OPT record for 'msg'.
 1042  *
 1043  * Requires:
 1044  *
 1045  *\li   'msg' is a valid message.
 1046  *
 1047  * Returns:
 1048  *
 1049  *\li   The OPT rdataset of 'msg', or NULL if there isn't one.
 1050  */
 1051 
 1052 isc_result_t
 1053 dns_message_setopt(dns_message_t *msg, dns_rdataset_t *opt);
 1054 /*%<
 1055  * Set the OPT record for 'msg'.
 1056  *
 1057  * Requires:
 1058  *
 1059  *\li   'msg' is a valid message with rendering intent
 1060  *  and no sections have been rendered.
 1061  *
 1062  *\li   'opt' is a valid OPT record.
 1063  *
 1064  * Ensures:
 1065  *
 1066  *\li   The OPT record has either been freed or ownership of it has
 1067  *  been transferred to the message.
 1068  *
 1069  *\li   If ISC_R_SUCCESS was returned, the OPT record will be rendered
 1070  *  when dns_message_renderend() is called.
 1071  *
 1072  * Returns:
 1073  *
 1074  *\li   #ISC_R_SUCCESS      -- all is well.
 1075  *
 1076  *\li   #ISC_R_NOSPACE      -- there is no space for the OPT record.
 1077  */
 1078 
 1079 dns_rdataset_t *
 1080 dns_message_gettsig(dns_message_t *msg, dns_name_t **owner);
 1081 /*%<
 1082  * Get the TSIG record and owner for 'msg'.
 1083  *
 1084  * Requires:
 1085  *
 1086  *\li   'msg' is a valid message.
 1087  *\li   'owner' is NULL or *owner is NULL.
 1088  *
 1089  * Returns:
 1090  *
 1091  *\li   The TSIG rdataset of 'msg', or NULL if there isn't one.
 1092  *
 1093  * Ensures:
 1094  *
 1095  * \li  If 'owner' is not NULL, it will point to the owner name.
 1096  */
 1097 
 1098 isc_result_t
 1099 dns_message_settsigkey(dns_message_t *msg, dns_tsigkey_t *key);
 1100 /*%<
 1101  * Set the tsig key for 'msg'.  This is only necessary for when rendering a
 1102  * query or parsing a response.  The key (if non-NULL) is attached to, and
 1103  * will be detached when the message is destroyed.
 1104  *
 1105  * Requires:
 1106  *
 1107  *\li   'msg' is a valid message with rendering intent,
 1108  *  dns_message_renderbegin() has been called, and no sections have been
 1109  *  rendered.
 1110  *\li   'key' is a valid tsig key or NULL.
 1111  *
 1112  * Returns:
 1113  *
 1114  *\li   #ISC_R_SUCCESS      -- all is well.
 1115  *
 1116  *\li   #ISC_R_NOSPACE      -- there is no space for the TSIG record.
 1117  */
 1118 
 1119 dns_tsigkey_t *
 1120 dns_message_gettsigkey(dns_message_t *msg);
 1121 /*%<
 1122  * Gets the tsig key for 'msg'.
 1123  *
 1124  * Requires:
 1125  *
 1126  *\li   'msg' is a valid message
 1127  */
 1128 
 1129 isc_result_t
 1130 dns_message_setquerytsig(dns_message_t *msg, isc_buffer_t *querytsig);
 1131 /*%<
 1132  * Indicates that 'querytsig' is the TSIG from the signed query for which
 1133  * 'msg' is the response.  This is also used for chained TSIGs in TCP
 1134  * responses.
 1135  *
 1136  * Requires:
 1137  *
 1138  *\li   'querytsig' is a valid buffer as returned by dns_message_getquerytsig()
 1139  *  or NULL
 1140  *
 1141  *\li   'msg' is a valid message
 1142  *
 1143  * Returns:
 1144  *
 1145  *\li   #ISC_R_SUCCESS
 1146  *\li   #ISC_R_NOMEMORY
 1147  */
 1148 
 1149 isc_result_t
 1150 dns_message_getquerytsig(dns_message_t *msg, isc_mem_t *mctx,
 1151              isc_buffer_t **querytsig);
 1152 /*%<
 1153  * Gets the tsig from the TSIG from the signed query 'msg'.  This is also used
 1154  * for chained TSIGs in TCP responses.  Unlike dns_message_gettsig, this makes
 1155  * a copy of the data, so can be used if the message is destroyed.
 1156  *
 1157  * Requires:
 1158  *
 1159  *\li   'msg' is a valid signed message
 1160  *\li   'mctx' is a valid memory context
 1161  *\li   querytsig != NULL && *querytsig == NULL
 1162  *
 1163  * Returns:
 1164  *
 1165  *\li   #ISC_R_SUCCESS
 1166  *\li   #ISC_R_NOMEMORY
 1167  *
 1168  * Ensures:
 1169  *\li   'tsig' points to NULL or an allocated buffer which must be freed
 1170  *  by the caller.
 1171  */
 1172 
 1173 dns_rdataset_t *
 1174 dns_message_getsig0(dns_message_t *msg, dns_name_t **owner);
 1175 /*%<
 1176  * Get the SIG(0) record and owner for 'msg'.
 1177  *
 1178  * Requires:
 1179  *
 1180  *\li   'msg' is a valid message.
 1181  *\li   'owner' is NULL or *owner is NULL.
 1182  *
 1183  * Returns:
 1184  *
 1185  *\li   The SIG(0) rdataset of 'msg', or NULL if there isn't one.
 1186  *
 1187  * Ensures:
 1188  *
 1189  * \li  If 'owner' is not NULL, it will point to the owner name.
 1190  */
 1191 
 1192 isc_result_t
 1193 dns_message_setsig0key(dns_message_t *msg, dst_key_t *key);
 1194 /*%<
 1195  * Set the SIG(0) key for 'msg'.
 1196  *
 1197  * Requires:
 1198  *
 1199  *\li   'msg' is a valid message with rendering intent,
 1200  *  dns_message_renderbegin() has been called, and no sections have been
 1201  *  rendered.
 1202  *\li   'key' is a valid sig key or NULL.
 1203  *
 1204  * Returns:
 1205  *
 1206  *\li   #ISC_R_SUCCESS      -- all is well.
 1207  *
 1208  *\li   #ISC_R_NOSPACE      -- there is no space for the SIG(0) record.
 1209  */
 1210 
 1211 dst_key_t *
 1212 dns_message_getsig0key(dns_message_t *msg);
 1213 /*%<
 1214  * Gets the SIG(0) key for 'msg'.
 1215  *
 1216  * Requires:
 1217  *
 1218  *\li   'msg' is a valid message
 1219  */
 1220 
 1221 void
 1222 dns_message_takebuffer(dns_message_t *msg, isc_buffer_t **buffer);
 1223 /*%<
 1224  * Give the *buffer to the message code to clean up when it is no
 1225  * longer needed.  This is usually when the message is reset or
 1226  * destroyed.
 1227  *
 1228  * Requires:
 1229  *
 1230  *\li   msg be a valid message.
 1231  *
 1232  *\li   buffer != NULL && *buffer is a valid isc_buffer_t, which was
 1233  *  dynamically allocated via isc_buffer_allocate().
 1234  */
 1235 
 1236 isc_result_t
 1237 dns_message_signer(dns_message_t *msg, dns_name_t *signer);
 1238 /*%<
 1239  * If this message was signed, return the identity of the signer.
 1240  * Unless ISC_R_NOTFOUND is returned, signer will reflect the name of the
 1241  * key that signed the message.
 1242  *
 1243  * Requires:
 1244  *
 1245  *\li   msg is a valid parsed message.
 1246  *\li   signer is a valid name
 1247  *
 1248  * Returns:
 1249  *
 1250  *\li   #ISC_R_SUCCESS      - the message was signed, and *signer
 1251  *                contains the signing identity
 1252  *
 1253  *\li   #ISC_R_NOTFOUND     - no TSIG or SIG(0) record is present in the
 1254  *                message
 1255  *
 1256  *\li   #DNS_R_TSIGVERIFYFAILURE    - the message was signed by a TSIG, but the
 1257  *                signature failed to verify
 1258  *
 1259  *\li   #DNS_R_TSIGERRORSET - the message was signed by a TSIG and
 1260  *                verified, but the query was rejected by
 1261  *                the server
 1262  *
 1263  *\li   #DNS_R_NOIDENTITY   - the message was signed by a TSIG and
 1264  *                verified, but the key has no identity since
 1265  *                it was generated by an unsigned TKEY process
 1266  *
 1267  *\li   #DNS_R_SIGINVALID   - the message was signed by a SIG(0), but
 1268  *                the signature failed to verify
 1269  *
 1270  *\li   #DNS_R_NOTVERIFIEDYET   - the message was signed by a TSIG or SIG(0),
 1271  *                but the signature has not been verified yet
 1272  */
 1273 
 1274 isc_result_t
 1275 dns_message_checksig(dns_message_t *msg, dns_view_t *view);
 1276 /*%<
 1277  * If this message was signed, verify the signature.
 1278  *
 1279  * Requires:
 1280  *
 1281  *\li   msg is a valid parsed message.
 1282  *\li   view is a valid view or NULL
 1283  *
 1284  * Returns:
 1285  *
 1286  *\li   #ISC_R_SUCCESS      - the message was unsigned, or the message
 1287  *                was signed correctly.
 1288  *
 1289  *\li   #DNS_R_EXPECTEDTSIG - A TSIG was expected, but not seen
 1290  *\li   #DNS_R_UNEXPECTEDTSIG   - A TSIG was seen but not expected
 1291  *\li   #DNS_R_TSIGVERIFYFAILURE - The TSIG failed to verify
 1292  */
 1293 
 1294 isc_result_t
 1295 dns_message_rechecksig(dns_message_t *msg, dns_view_t *view);
 1296 /*%<
 1297  * Reset the signature state and then if the message was signed,
 1298  * verify the message.
 1299  *
 1300  * Requires:
 1301  *
 1302  *\li   msg is a valid parsed message.
 1303  *\li   view is a valid view or NULL
 1304  *
 1305  * Returns:
 1306  *
 1307  *\li   #ISC_R_SUCCESS      - the message was unsigned, or the message
 1308  *                was signed correctly.
 1309  *
 1310  *\li   #DNS_R_EXPECTEDTSIG - A TSIG was expected, but not seen
 1311  *\li   #DNS_R_UNEXPECTEDTSIG   - A TSIG was seen but not expected
 1312  *\li   #DNS_R_TSIGVERIFYFAILURE - The TSIG failed to verify
 1313  */
 1314 
 1315 void
 1316 dns_message_resetsig(dns_message_t *msg);
 1317 /*%<
 1318  * Reset the signature state.
 1319  *
 1320  * Requires:
 1321  *\li   'msg' is a valid parsed message.
 1322  */
 1323 
 1324 isc_region_t *
 1325 dns_message_getrawmessage(dns_message_t *msg);
 1326 /*%<
 1327  * Retrieve the raw message in compressed wire format.  The message must
 1328  * have been successfully parsed for it to have been saved.
 1329  *
 1330  * Requires:
 1331  *\li   msg is a valid parsed message.
 1332  *
 1333  * Returns:
 1334  *\li   NULL    if there is no saved message.
 1335  *  a pointer to a region which refers the dns message.
 1336  */
 1337 
 1338 void
 1339 dns_message_setsortorder(dns_message_t *msg, dns_rdatasetorderfunc_t order,
 1340              const void *order_arg);
 1341 /*%<
 1342  * Define the order in which RR sets get rendered by
 1343  * dns_message_rendersection() to be the ascending order
 1344  * defined by the integer value returned by 'order' when
 1345  * given each RR and 'arg' as arguments.  If 'order' and
 1346  * 'order_arg' are NULL, a default order is used.
 1347  *
 1348  * Requires:
 1349  *\li   msg be a valid message.
 1350  *\li   order_arg is NULL if and only if order is NULL.
 1351  */
 1352 
 1353 void
 1354 dns_message_settimeadjust(dns_message_t *msg, int timeadjust);
 1355 /*%<
 1356  * Adjust the time used to sign/verify a message by timeadjust.
 1357  * Currently only TSIG.
 1358  *
 1359  * Requires:
 1360  *\li   msg be a valid message.
 1361  */
 1362 
 1363 int
 1364 dns_message_gettimeadjust(dns_message_t *msg);
 1365 /*%<
 1366  * Return the current time adjustment.
 1367  *
 1368  * Requires:
 1369  *\li   msg be a valid message.
 1370  */
 1371 
 1372 void
 1373 dns_message_logpacket(dns_message_t *message, const char *description,
 1374               isc_logcategory_t *category, isc_logmodule_t *module,
 1375               int level, isc_mem_t *mctx);
 1376 void
 1377 dns_message_logpacket2(dns_message_t *message,
 1378                const char *description, isc_sockaddr_t *address,
 1379                isc_logcategory_t *category, isc_logmodule_t *module,
 1380                int level, isc_mem_t *mctx);
 1381 void
 1382 dns_message_logfmtpacket(dns_message_t *message, const char *description,
 1383              isc_logcategory_t *category, isc_logmodule_t *module,
 1384              const dns_master_style_t *style, int level,
 1385              isc_mem_t *mctx);
 1386 void
 1387 dns_message_logfmtpacket2(dns_message_t *message,
 1388               const char *description, isc_sockaddr_t *address,
 1389               isc_logcategory_t *category, isc_logmodule_t *module,
 1390               const dns_master_style_t *style, int level,
 1391               isc_mem_t *mctx);
 1392 /*%<
 1393  * Log 'message' at the specified logging parameters.
 1394  *
 1395  * For dns_message_logpacket and dns_message_logfmtpacket expect the
 1396  * 'description' to end in a newline.
 1397  *
 1398  * For dns_message_logpacket2 and dns_message_logfmtpacket2
 1399  * 'description' will be emitted at the start of the message followed
 1400  * by the formatted address and a newline.
 1401  *
 1402  * Requires:
 1403  * \li   message be a valid.
 1404  * \li   description to be non NULL.
 1405  * \li   address to be non NULL.
 1406  * \li   category to be valid.
 1407  * \li   module to be valid.
 1408  * \li   style to be valid.
 1409  * \li   mctx to be a valid.
 1410  */
 1411 
 1412 isc_result_t
 1413 dns_message_buildopt(dns_message_t *msg, dns_rdataset_t **opt,
 1414              unsigned int version, uint16_t udpsize,
 1415              unsigned int flags, dns_ednsopt_t *ednsopts, size_t count);
 1416 /*%<
 1417  * Built a opt record.
 1418  *
 1419  * Requires:
 1420  * \li   msg be a valid message.
 1421  * \li   opt to be a non NULL and *opt to be NULL.
 1422  *
 1423  * Returns:
 1424  * \li   ISC_R_SUCCESS on success.
 1425  * \li   ISC_R_NOMEMORY
 1426  * \li   ISC_R_NOSPACE
 1427  * \li   other.
 1428  */
 1429 
 1430 void
 1431 dns_message_setclass(dns_message_t *msg, dns_rdataclass_t rdclass);
 1432 /*%<
 1433  * Set the expected class of records in the response.
 1434  *
 1435  * Requires:
 1436  * \li   msg be a valid message with parsing intent.
 1437  */
 1438 
 1439 ISC_LANG_ENDDECLS
 1440 
 1441 #endif /* DNS_MESSAGE_H */