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

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