contrib/bind9/lib/dns/include/dns/message.h

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