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

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