contrib/bind-9.5.2/lib/dns/include/dns/message.h

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