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

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