message.h

Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2004-2010, 2012-2014  Internet Systems Consortium, Inc. ("ISC")
00003  * Copyright (C) 1999-2003  Internet Software Consortium.
00004  *
00005  * Permission to use, copy, modify, and/or distribute this software for any
00006  * purpose with or without fee is hereby granted, provided that the above
00007  * copyright notice and this permission notice appear in all copies.
00008  *
00009  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
00010  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
00011  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
00012  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
00013  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
00014  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
00015  * PERFORMANCE OF THIS SOFTWARE.
00016  */
00017 
00018 /* $Id$ */
00019 
00020 #ifndef DNS_MESSAGE_H
00021 #define DNS_MESSAGE_H 1
00022 
00023 /***
00024  ***    Imports
00025  ***/
00026 
00027 #include <isc/lang.h>
00028 #include <isc/magic.h>
00029 
00030 #include <dns/compress.h>
00031 #include <dns/masterdump.h>
00032 #include <dns/types.h>
00033 
00034 #include <dst/dst.h>
00035 
00036 /*! \file dns/message.h
00037  * \brief Message Handling Module
00038  *
00039  * How this beast works:
00040  *
00041  * When a dns message is received in a buffer, dns_message_fromwire() is called
00042  * on the memory region.  Various items are checked including the format
00043  * of the message (if counts are right, if counts consume the entire sections,
00044  * and if sections consume the entire message) and known pseudo-RRs in the
00045  * additional data section are analyzed and removed.
00046  *
00047  * TSIG checking is also done at this layer, and any DNSSEC transaction
00048  * signatures should also be checked here.
00049  *
00050  * Notes on using the gettemp*() and puttemp*() functions:
00051  *
00052  * These functions return items (names, rdatasets, etc) allocated from some
00053  * internal state of the dns_message_t.
00054  *
00055  * Names and rdatasets must be put back into the dns_message_t in
00056  * one of two ways.  Assume a name was allocated via
00057  * dns_message_gettempname():
00058  *
00059  *\li   (1) insert it into a section, using dns_message_addname().
00060  *
00061  *\li   (2) return it to the message using dns_message_puttempname().
00062  *
00063  * The same applies to rdatasets.
00064  *
00065  * On the other hand, offsets, rdatalists and rdatas allocated using
00066  * dns_message_gettemp*() will always be freed automatically
00067  * when the message is reset or destroyed; calling dns_message_puttemp*()
00068  * on rdatalists and rdatas is optional and serves only to enable the item
00069  * to be reused multiple times during the lifetime of the message; offsets
00070  * cannot be reused.
00071  *
00072  * Buffers allocated using isc_buffer_allocate() can be automatically freed
00073  * as well by giving the buffer to the message using dns_message_takebuffer().
00074  * Doing this will cause the buffer to be freed using isc_buffer_free()
00075  * when the section lists are cleared, such as in a reset or in a destroy.
00076  * Since the buffer itself exists until the message is destroyed, this sort
00077  * of code can be written:
00078  *
00079  * \code
00080  *      buffer = isc_buffer_allocate(mctx, 512);
00081  *      name = NULL;
00082  *      name = dns_message_gettempname(message, &name);
00083  *      dns_name_init(name, NULL);
00084  *      result = dns_name_fromtext(name, &source, dns_rootname, 0, buffer);
00085  *      dns_message_takebuffer(message, &buffer);
00086  * \endcode
00087  *
00088  *
00089  * TODO:
00090  *
00091  * XXX Needed:  ways to set and retrieve EDNS information, add rdata to a
00092  * section, move rdata from one section to another, remove rdata, etc.
00093  */
00094 
00095 #define DNS_MESSAGEFLAG_QR              0x8000U
00096 #define DNS_MESSAGEFLAG_AA              0x0400U
00097 #define DNS_MESSAGEFLAG_TC              0x0200U
00098 #define DNS_MESSAGEFLAG_RD              0x0100U
00099 #define DNS_MESSAGEFLAG_RA              0x0080U
00100 #define DNS_MESSAGEFLAG_AD              0x0020U
00101 #define DNS_MESSAGEFLAG_CD              0x0010U
00102 
00103 /*%< EDNS0 extended message flags */
00104 #define DNS_MESSAGEEXTFLAG_DO           0x8000U
00105 
00106 /*%< EDNS0 extended OPT codes */
00107 #define DNS_OPT_NSID            0x0003          /*%< NSID opt code */
00108 #define DNS_OPT_CLIENT_SUBNET   0x0008          /*%< client subnet opt code */
00109 #define DNS_OPT_EXPIRE          0x0009          /*%< EXPIRE opt code */
00110 
00111 /*%< Experimental options [65001...65534] as per RFC6891 */
00112 #define DNS_OPT_SIT             65001           /*%< SIT opt code */
00113 
00114 /*%< The number of EDNS options we know about. */
00115 #define DNS_EDNSOPTIONS 5
00116 
00117 #define DNS_MESSAGE_REPLYPRESERVE       (DNS_MESSAGEFLAG_RD|DNS_MESSAGEFLAG_CD)
00118 #define DNS_MESSAGEEXTFLAG_REPLYPRESERVE (DNS_MESSAGEEXTFLAG_DO)
00119 
00120 #define DNS_MESSAGE_HEADERLEN           12 /*%< 6 isc_uint16_t's */
00121 
00122 #define DNS_MESSAGE_MAGIC               ISC_MAGIC('M','S','G','@')
00123 #define DNS_MESSAGE_VALID(msg)          ISC_MAGIC_VALID(msg, DNS_MESSAGE_MAGIC)
00124 
00125 /*
00126  * Ordering here matters.  DNS_SECTION_ANY must be the lowest and negative,
00127  * and DNS_SECTION_MAX must be one greater than the last used section.
00128  */
00129 typedef int dns_section_t;
00130 #define DNS_SECTION_ANY                 (-1)
00131 #define DNS_SECTION_QUESTION            0
00132 #define DNS_SECTION_ANSWER              1
00133 #define DNS_SECTION_AUTHORITY           2
00134 #define DNS_SECTION_ADDITIONAL          3
00135 #define DNS_SECTION_MAX                 4
00136 
00137 typedef int dns_pseudosection_t;
00138 #define DNS_PSEUDOSECTION_ANY           (-1)
00139 #define DNS_PSEUDOSECTION_OPT           0
00140 #define DNS_PSEUDOSECTION_TSIG          1
00141 #define DNS_PSEUDOSECTION_SIG0          2
00142 #define DNS_PSEUDOSECTION_MAX           3
00143 
00144 typedef int dns_messagetextflag_t;
00145 #define DNS_MESSAGETEXTFLAG_NOCOMMENTS  0x0001
00146 #define DNS_MESSAGETEXTFLAG_NOHEADERS   0x0002
00147 #define DNS_MESSAGETEXTFLAG_ONESOA      0x0004
00148 #define DNS_MESSAGETEXTFLAG_OMITSOA     0x0008
00149 #define DNS_MESSAGETEXTFLAG_COMMENTDATA 0x0010
00150 
00151 /*
00152  * Dynamic update names for these sections.
00153  */
00154 #define DNS_SECTION_ZONE                DNS_SECTION_QUESTION
00155 #define DNS_SECTION_PREREQUISITE        DNS_SECTION_ANSWER
00156 #define DNS_SECTION_UPDATE              DNS_SECTION_AUTHORITY
00157 
00158 /*
00159  * These tell the message library how the created dns_message_t will be used.
00160  */
00161 #define DNS_MESSAGE_INTENTUNKNOWN       0 /*%< internal use only */
00162 #define DNS_MESSAGE_INTENTPARSE         1 /*%< parsing messages */
00163 #define DNS_MESSAGE_INTENTRENDER        2 /*%< rendering */
00164 
00165 /*
00166  * Control behavior of parsing
00167  */
00168 #define DNS_MESSAGEPARSE_PRESERVEORDER  0x0001  /*%< preserve rdata order */
00169 #define DNS_MESSAGEPARSE_BESTEFFORT     0x0002  /*%< return a message if a
00170                                                    recoverable parse error
00171                                                    occurs */
00172 #define DNS_MESSAGEPARSE_CLONEBUFFER    0x0004  /*%< save a copy of the
00173                                                    source buffer */
00174 #define DNS_MESSAGEPARSE_IGNORETRUNCATION 0x0008 /*%< truncation errors are
00175                                                   * not fatal. */
00176 
00177 /*
00178  * Control behavior of rendering
00179  */
00180 #define DNS_MESSAGERENDER_ORDERED       0x0001  /*%< don't change order */
00181 #define DNS_MESSAGERENDER_PARTIAL       0x0002  /*%< allow a partial rdataset */
00182 #define DNS_MESSAGERENDER_OMITDNSSEC    0x0004  /*%< omit DNSSEC records */
00183 #define DNS_MESSAGERENDER_PREFER_A      0x0008  /*%< prefer A records in
00184                                                       additional section. */
00185 #define DNS_MESSAGERENDER_PREFER_AAAA   0x0010  /*%< prefer AAAA records in
00186                                                   additional section. */
00187 #ifdef ALLOW_FILTER_AAAA
00188 #define DNS_MESSAGERENDER_FILTER_AAAA   0x0020  /*%< filter AAAA records */
00189 #endif
00190 
00191 typedef struct dns_msgblock dns_msgblock_t;
00192 
00193 struct dns_message {
00194         /* public from here down */
00195         unsigned int                    magic;
00196 
00197         dns_messageid_t                 id;
00198         unsigned int                    flags;
00199         dns_rcode_t                     rcode;
00200         unsigned int                    opcode;
00201         dns_rdataclass_t                rdclass;
00202 
00203         /* 4 real, 1 pseudo */
00204         unsigned int                    counts[DNS_SECTION_MAX];
00205 
00206         /* private from here down */
00207         dns_namelist_t                  sections[DNS_SECTION_MAX];
00208         dns_name_t                     *cursors[DNS_SECTION_MAX];
00209         dns_rdataset_t                 *opt;
00210         dns_rdataset_t                 *sig0;
00211         dns_rdataset_t                 *tsig;
00212 
00213         int                             state;
00214         unsigned int                    from_to_wire : 2;
00215         unsigned int                    header_ok : 1;
00216         unsigned int                    question_ok : 1;
00217         unsigned int                    tcp_continuation : 1;
00218         unsigned int                    verified_sig : 1;
00219         unsigned int                    verify_attempted : 1;
00220         unsigned int                    free_query : 1;
00221         unsigned int                    free_saved : 1;
00222         unsigned int                    sitok : 1;
00223         unsigned int                    sitbad : 1;
00224 
00225         unsigned int                    opt_reserved;
00226         unsigned int                    sig_reserved;
00227         unsigned int                    reserved; /* reserved space (render) */
00228 
00229         isc_buffer_t                   *buffer;
00230         dns_compress_t                 *cctx;
00231 
00232         isc_mem_t                      *mctx;
00233         isc_mempool_t                  *namepool;
00234         isc_mempool_t                  *rdspool;
00235 
00236         isc_bufferlist_t                scratchpad;
00237         isc_bufferlist_t                cleanup;
00238 
00239         ISC_LIST(dns_msgblock_t)        rdatas;
00240         ISC_LIST(dns_msgblock_t)        rdatalists;
00241         ISC_LIST(dns_msgblock_t)        offsets;
00242 
00243         ISC_LIST(dns_rdata_t)           freerdata;
00244         ISC_LIST(dns_rdatalist_t)       freerdatalist;
00245 
00246         dns_rcode_t                     tsigstatus;
00247         dns_rcode_t                     querytsigstatus;
00248         dns_name_t                     *tsigname; /* Owner name of TSIG, if any */
00249         dns_rdataset_t                 *querytsig;
00250         dns_tsigkey_t                  *tsigkey;
00251         dst_context_t                  *tsigctx;
00252         int                             sigstart;
00253         int                             timeadjust;
00254 
00255         dns_name_t                     *sig0name; /* Owner name of SIG0, if any */
00256         dst_key_t                      *sig0key;
00257         dns_rcode_t                     sig0status;
00258         isc_region_t                    query;
00259         isc_region_t                    saved;
00260 
00261         dns_rdatasetorderfunc_t         order;
00262         const void *                    order_arg;
00263 };
00264 
00265 struct dns_ednsopt {
00266         isc_uint16_t                    code;
00267         isc_uint16_t                    length;
00268         unsigned char                   *value;
00269 };
00270 
00271 /***
00272  *** Functions
00273  ***/
00274 
00275 ISC_LANG_BEGINDECLS
00276 
00277 isc_result_t
00278 dns_message_create(isc_mem_t *mctx, unsigned int intent, dns_message_t **msgp);
00279 
00280 /*%<
00281  * Create msg structure.
00282  *
00283  * This function will allocate some internal blocks of memory that are
00284  * expected to be needed for parsing or rendering nearly any type of message.
00285  *
00286  * Requires:
00287  *\li   'mctx' be a valid memory context.
00288  *
00289  *\li   'msgp' be non-null and '*msg' be NULL.
00290  *
00291  *\li   'intent' must be one of DNS_MESSAGE_INTENTPARSE or
00292  *      #DNS_MESSAGE_INTENTRENDER.
00293  *
00294  * Ensures:
00295  *\li   The data in "*msg" is set to indicate an unused and empty msg
00296  *      structure.
00297  *
00298  * Returns:
00299  *\li   #ISC_R_NOMEMORY         -- out of memory
00300  *\li   #ISC_R_SUCCESS          -- success
00301  */
00302 
00303 void
00304 dns_message_reset(dns_message_t *msg, unsigned int intent);
00305 /*%<
00306  * Reset a message structure to default state.  All internal lists are freed
00307  * or reset to a default state as well.  This is simply a more efficient
00308  * way to call dns_message_destroy() followed by dns_message_allocate(),
00309  * since it avoid many memory allocations.
00310  *
00311  * If any data loanouts (buffers, names, rdatas, etc) were requested,
00312  * the caller must no longer use them after this call.
00313  *
00314  * The intended next use of the message will be 'intent'.
00315  *
00316  * Requires:
00317  *
00318  *\li   'msg' be valid.
00319  *
00320  *\li   'intent' is DNS_MESSAGE_INTENTPARSE or DNS_MESSAGE_INTENTRENDER
00321  */
00322 
00323 void
00324 dns_message_destroy(dns_message_t **msgp);
00325 /*%<
00326  * Destroy all state in the message.
00327  *
00328  * Requires:
00329  *
00330  *\li   'msgp' be valid.
00331  *
00332  * Ensures:
00333  *\li   '*msgp' == NULL
00334  */
00335 
00336 isc_result_t
00337 dns_message_sectiontotext(dns_message_t *msg, dns_section_t section,
00338                           const dns_master_style_t *style,
00339                           dns_messagetextflag_t flags,
00340                           isc_buffer_t *target);
00341 
00342 isc_result_t
00343 dns_message_pseudosectiontotext(dns_message_t *msg,
00344                                 dns_pseudosection_t section,
00345                                 const dns_master_style_t *style,
00346                                 dns_messagetextflag_t flags,
00347                                 isc_buffer_t *target);
00348 /*%<
00349  * Convert section 'section' or 'pseudosection' of message 'msg' to
00350  * a cleartext representation
00351  *
00352  * Notes:
00353  *     \li See dns_message_totext for meanings of flags.
00354  *
00355  * Requires:
00356  *
00357  *\li   'msg' is a valid message.
00358  *
00359  *\li   'style' is a valid master dump style.
00360  *
00361  *\li   'target' is a valid buffer.
00362  *
00363  *\li   'section' is a valid section label.
00364  *
00365  * Ensures:
00366  *
00367  *\li   If the result is success:
00368  *              The used space in 'target' is updated.
00369  *
00370  * Returns:
00371  *
00372  *\li   #ISC_R_SUCCESS
00373  *\li   #ISC_R_NOSPACE
00374  *\li   #ISC_R_NOMORE
00375  *
00376  *\li   Note: On error return, *target may be partially filled with data.
00377 */
00378 
00379 isc_result_t
00380 dns_message_totext(dns_message_t *msg, const dns_master_style_t *style,
00381                    dns_messagetextflag_t flags, isc_buffer_t *target);
00382 /*%<
00383  * Convert all sections of message 'msg' to a cleartext representation
00384  *
00385  * Notes:
00386  * \li     In flags, If #DNS_MESSAGETEXTFLAG_OMITDOT is set, then the
00387  *      final '.' in absolute names will not be emitted.  If
00388  *      #DNS_MESSAGETEXTFLAG_NOCOMMENTS is cleared, lines beginning
00389  *      with ";;" will be emitted indicating section name.  If
00390  *      #DNS_MESSAGETEXTFLAG_NOHEADERS is cleared, header lines will
00391  *      be emitted.
00392  *
00393  *      If #DNS_MESSAGETEXTFLAG_ONESOA is set then only print the
00394  *      first SOA record in the answer section.  If
00395  *      #DNS_MESSAGETEXTFLAG_OMITSOA is set don't print any SOA records
00396  *      in the answer section.  These are useful for suppressing the
00397  *      display of the second SOA record in a AXFR by setting
00398  *      #DNS_MESSAGETEXTFLAG_ONESOA on the first message in a AXFR stream
00399  *      and #DNS_MESSAGETEXTFLAG_OMITSOA on subsequent messages.
00400  *
00401  * Requires:
00402  *
00403  *\li   'msg' is a valid message.
00404  *
00405  *\li   'style' is a valid master dump style.
00406  *
00407  *\li   'target' is a valid buffer.
00408  *
00409  * Ensures:
00410  *
00411  *\li   If the result is success:
00412  *              The used space in 'target' is updated.
00413  *
00414  * Returns:
00415  *
00416  *\li   #ISC_R_SUCCESS
00417  *\li   #ISC_R_NOSPACE
00418  *\li   #ISC_R_NOMORE
00419  *
00420  *\li   Note: On error return, *target may be partially filled with data.
00421  */
00422 
00423 isc_result_t
00424 dns_message_parse(dns_message_t *msg, isc_buffer_t *source,
00425                   unsigned int options);
00426 /*%<
00427  * Parse raw wire data in 'source' as a DNS message.
00428  *
00429  * OPT records are detected and stored in the pseudo-section "opt".
00430  * TSIGs are detected and stored in the pseudo-section "tsig".
00431  *
00432  * If #DNS_MESSAGEPARSE_PRESERVEORDER is set, or if the opcode of the message
00433  * is UPDATE, a separate dns_name_t object will be created for each RR in the
00434  * message.  Each such dns_name_t will have a single rdataset containing the
00435  * single RR, and the order of the RRs in the message is preserved.
00436  * Otherwise, only one dns_name_t object will be created for each unique
00437  * owner name in the section, and each such dns_name_t will have a list
00438  * of rdatasets.  To access the names and their data, use
00439  * dns_message_firstname() and dns_message_nextname().
00440  *
00441  * If #DNS_MESSAGEPARSE_BESTEFFORT is set, errors in message content will
00442  * not be considered FORMERRs.  If the entire message can be parsed, it
00443  * will be returned and DNS_R_RECOVERABLE will be returned.
00444  *
00445  * If #DNS_MESSAGEPARSE_IGNORETRUNCATION is set then return as many complete
00446  * RR's as possible, DNS_R_RECOVERABLE will be returned.
00447  *
00448  * OPT and TSIG records are always handled specially, regardless of the
00449  * 'preserve_order' setting.
00450  *
00451  * Requires:
00452  *\li   "msg" be valid.
00453  *
00454  *\li   "buffer" be a wire format buffer.
00455  *
00456  * Ensures:
00457  *\li   The buffer's data format is correct.
00458  *
00459  *\li   The buffer's contents verify as correct regarding header bits, buffer
00460  *      and rdata sizes, etc.
00461  *
00462  * Returns:
00463  *\li   #ISC_R_SUCCESS          -- all is well
00464  *\li   #ISC_R_NOMEMORY         -- no memory
00465  *\li   #DNS_R_RECOVERABLE      -- the message parsed properly, but contained
00466  *                                 errors.
00467  *\li   Many other errors possible XXXMLG
00468  */
00469 
00470 isc_result_t
00471 dns_message_renderbegin(dns_message_t *msg, dns_compress_t *cctx,
00472                         isc_buffer_t *buffer);
00473 /*%<
00474  * Begin rendering on a message.  Only one call can be made to this function
00475  * per message.
00476  *
00477  * The compression context is "owned" by the message library until
00478  * dns_message_renderend() is called.  It must be invalidated by the caller.
00479  *
00480  * The buffer is "owned" by the message library until dns_message_renderend()
00481  * is called.
00482  *
00483  * Requires:
00484  *
00485  *\li   'msg' be valid.
00486  *
00487  *\li   'cctx' be valid.
00488  *
00489  *\li   'buffer' is a valid buffer.
00490  *
00491  * Side Effects:
00492  *
00493  *\li   The buffer is cleared before it is used.
00494  *
00495  * Returns:
00496  *\li   #ISC_R_SUCCESS          -- all is well
00497  *\li   #ISC_R_NOSPACE          -- output buffer is too small
00498  */
00499 
00500 isc_result_t
00501 dns_message_renderchangebuffer(dns_message_t *msg, isc_buffer_t *buffer);
00502 /*%<
00503  * Reset the buffer.  This can be used after growing the old buffer
00504  * on a ISC_R_NOSPACE return from most of the render functions.
00505  *
00506  * On successful completion, the old buffer is no longer used by the
00507  * library.  The new buffer is owned by the library until
00508  * dns_message_renderend() is called.
00509  *
00510  * Requires:
00511  *
00512  *\li   'msg' be valid.
00513  *
00514  *\li   dns_message_renderbegin() was called.
00515  *
00516  *\li   buffer != NULL.
00517  *
00518  * Returns:
00519  *\li   #ISC_R_NOSPACE          -- new buffer is too small
00520  *\li   #ISC_R_SUCCESS          -- all is well.
00521  */
00522 
00523 isc_result_t
00524 dns_message_renderreserve(dns_message_t *msg, unsigned int space);
00525 /*%<
00526  * XXXMLG should use size_t rather than unsigned int once the buffer
00527  * API is cleaned up
00528  *
00529  * Reserve "space" bytes in the given buffer.
00530  *
00531  * Requires:
00532  *
00533  *\li   'msg' be valid.
00534  *
00535  *\li   dns_message_renderbegin() was called.
00536  *
00537  * Returns:
00538  *\li   #ISC_R_SUCCESS          -- all is well.
00539  *\li   #ISC_R_NOSPACE          -- not enough free space in the buffer.
00540  */
00541 
00542 void
00543 dns_message_renderrelease(dns_message_t *msg, unsigned int space);
00544 /*%<
00545  * XXXMLG should use size_t rather than unsigned int once the buffer
00546  * API is cleaned up
00547  *
00548  * Release "space" bytes in the given buffer that was previously reserved.
00549  *
00550  * Requires:
00551  *
00552  *\li   'msg' be valid.
00553  *
00554  *\li   'space' is less than or equal to the total amount of space reserved
00555  *      via prior calls to dns_message_renderreserve().
00556  *
00557  *\li   dns_message_renderbegin() was called.
00558  */
00559 
00560 isc_result_t
00561 dns_message_rendersection(dns_message_t *msg, dns_section_t section,
00562                           unsigned int options);
00563 /*%<
00564  * Render all names, rdatalists, etc from the given section at the
00565  * specified priority or higher.
00566  *
00567  * Requires:
00568  *\li   'msg' be valid.
00569  *
00570  *\li   'section' be a valid section.
00571  *
00572  *\li   dns_message_renderbegin() was called.
00573  *
00574  * Returns:
00575  *\li   #ISC_R_SUCCESS          -- all records were written, and there are
00576  *                                 no more records for this section.
00577  *\li   #ISC_R_NOSPACE          -- Not enough room in the buffer to write
00578  *                                 all records requested.
00579  *\li   #DNS_R_MOREDATA         -- All requested records written, and there
00580  *                                 are records remaining for this section.
00581  */
00582 
00583 void
00584 dns_message_renderheader(dns_message_t *msg, isc_buffer_t *target);
00585 /*%<
00586  * Render the message header.  This is implicitly called by
00587  * dns_message_renderend().
00588  *
00589  * Requires:
00590  *
00591  *\li   'msg' be a valid message.
00592  *
00593  *\li   dns_message_renderbegin() was called.
00594  *
00595  *\li   'target' is a valid buffer with enough space to hold a message header
00596  */
00597 
00598 isc_result_t
00599 dns_message_renderend(dns_message_t *msg);
00600 /*%<
00601  * Finish rendering to the buffer.  Note that more data can be in the
00602  * 'msg' structure.  Destroying the structure will free this, or in a multi-
00603  * part EDNS1 message this data can be rendered to another buffer later.
00604  *
00605  * Requires:
00606  *
00607  *\li   'msg' be a valid message.
00608  *
00609  *\li   dns_message_renderbegin() was called.
00610  *
00611  * Returns:
00612  *\li   #ISC_R_SUCCESS          -- all is well.
00613  */
00614 
00615 void
00616 dns_message_renderreset(dns_message_t *msg);
00617 /*%<
00618  * Reset the message so that it may be rendered again.
00619  *
00620  * Notes:
00621  *
00622  *\li   If dns_message_renderbegin() has been called, dns_message_renderend()
00623  *      must be called before calling this function.
00624  *
00625  * Requires:
00626  *
00627  *\li   'msg' be a valid message with rendering intent.
00628  */
00629 
00630 isc_result_t
00631 dns_message_firstname(dns_message_t *msg, dns_section_t section);
00632 /*%<
00633  * Set internal per-section name pointer to the beginning of the section.
00634  *
00635  * The functions dns_message_firstname() and dns_message_nextname() may
00636  * be used for iterating over the owner names in a section.
00637  *
00638  * Requires:
00639  *
00640  *\li           'msg' be valid.
00641  *
00642  *\li   'section' be a valid section.
00643  *
00644  * Returns:
00645  *\li   #ISC_R_SUCCESS          -- All is well.
00646  *\li   #ISC_R_NOMORE           -- No names on given section.
00647  */
00648 
00649 isc_result_t
00650 dns_message_nextname(dns_message_t *msg, dns_section_t section);
00651 /*%<
00652  * Sets the internal per-section name pointer to point to the next name
00653  * in that section.
00654  *
00655  * Requires:
00656  *
00657  * \li          'msg' be valid.
00658  *
00659  *\li   'section' be a valid section.
00660  *
00661  *\li   dns_message_firstname() must have been called on this section,
00662  *      and the result was ISC_R_SUCCESS.
00663  *
00664  * Returns:
00665  *\li   #ISC_R_SUCCESS          -- All is well.
00666  *\li   #ISC_R_NOMORE           -- No more names in given section.
00667  */
00668 
00669 void
00670 dns_message_currentname(dns_message_t *msg, dns_section_t section,
00671                         dns_name_t **name);
00672 /*%<
00673  * Sets 'name' to point to the name where the per-section internal name
00674  * pointer is currently set.
00675  *
00676  * This function returns the name in the database, so any data associated
00677  * with it (via the name's "list" member) contains the actual rdatasets.
00678  *
00679  * Requires:
00680  *
00681  *\li   'msg' be valid.
00682  *
00683  *\li   'name' be non-NULL, and *name be NULL.
00684  *
00685  *\li   'section' be a valid section.
00686  *
00687  *\li   dns_message_firstname() must have been called on this section,
00688  *      and the result of it and any dns_message_nextname() calls was
00689  *      #ISC_R_SUCCESS.
00690  */
00691 
00692 isc_result_t
00693 dns_message_findname(dns_message_t *msg, dns_section_t section,
00694                      dns_name_t *target, dns_rdatatype_t type,
00695                      dns_rdatatype_t covers, dns_name_t **foundname,
00696                      dns_rdataset_t **rdataset);
00697 /*%<
00698  * Search for a name in the specified section.  If it is found, *name is
00699  * set to point to the name, and *rdataset is set to point to the found
00700  * rdataset (if type is specified as other than dns_rdatatype_any).
00701  *
00702  * Requires:
00703  *\li   'msg' be valid.
00704  *
00705  *\li   'section' be a valid section.
00706  *
00707  *\li   If a pointer to the name is desired, 'foundname' should be non-NULL.
00708  *      If it is non-NULL, '*foundname' MUST be NULL.
00709  *
00710  *\li   If a type other than dns_datatype_any is searched for, 'rdataset'
00711  *      may be non-NULL, '*rdataset' be NULL, and will point at the found
00712  *      rdataset.  If the type is dns_datatype_any, 'rdataset' must be NULL.
00713  *
00714  *\li   'target' be a valid name.
00715  *
00716  *\li   'type' be a valid type.
00717  *
00718  *\li   If 'type' is dns_rdatatype_rrsig, 'covers' must be a valid type.
00719  *      Otherwise it should be 0.
00720  *
00721  * Returns:
00722  *\li   #ISC_R_SUCCESS          -- all is well.
00723  *\li   #DNS_R_NXDOMAIN         -- name does not exist in that section.
00724  *\li   #DNS_R_NXRRSET          -- The name does exist, but the desired
00725  *                                 type does not.
00726  */
00727 
00728 isc_result_t
00729 dns_message_findtype(dns_name_t *name, dns_rdatatype_t type,
00730                      dns_rdatatype_t covers, dns_rdataset_t **rdataset);
00731 /*%<
00732  * Search the name for the specified type.  If it is found, *rdataset is
00733  * filled in with a pointer to that rdataset.
00734  *
00735  * Requires:
00736  *\li   if '**rdataset' is non-NULL, *rdataset needs to be NULL.
00737  *
00738  *\li   'type' be a valid type, and NOT dns_rdatatype_any.
00739  *
00740  *\li   If 'type' is dns_rdatatype_rrsig, 'covers' must be a valid type.
00741  *      Otherwise it should be 0.
00742  *
00743  * Returns:
00744  *\li   #ISC_R_SUCCESS          -- all is well.
00745  *\li   #ISC_R_NOTFOUND         -- the desired type does not exist.
00746  */
00747 
00748 isc_result_t
00749 dns_message_find(dns_name_t *name, dns_rdataclass_t rdclass,
00750                  dns_rdatatype_t type, dns_rdatatype_t covers,
00751                  dns_rdataset_t **rdataset);
00752 /*%<
00753  * Search the name for the specified rdclass and type.  If it is found,
00754  * *rdataset is filled in with a pointer to that rdataset.
00755  *
00756  * Requires:
00757  *\li   if '**rdataset' is non-NULL, *rdataset needs to be NULL.
00758  *
00759  *\li   'type' be a valid type, and NOT dns_rdatatype_any.
00760  *
00761  *\li   If 'type' is dns_rdatatype_rrsig, 'covers' must be a valid type.
00762  *      Otherwise it should be 0.
00763  *
00764  * Returns:
00765  *\li   #ISC_R_SUCCESS          -- all is well.
00766  *\li   #ISC_R_NOTFOUND         -- the desired type does not exist.
00767  */
00768 
00769 void
00770 dns_message_movename(dns_message_t *msg, dns_name_t *name,
00771                      dns_section_t fromsection,
00772                      dns_section_t tosection);
00773 /*%<
00774  * Move a name from one section to another.
00775  *
00776  * Requires:
00777  *
00778  *\li   'msg' be valid.
00779  *
00780  *\li   'name' must be a name already in 'fromsection'.
00781  *
00782  *\li   'fromsection' must be a valid section.
00783  *
00784  *\li   'tosection' must be a valid section.
00785  */
00786 
00787 void
00788 dns_message_addname(dns_message_t *msg, dns_name_t *name,
00789                     dns_section_t section);
00790 /*%<
00791  * Adds the name to the given section.
00792  *
00793  * It is the caller's responsibility to enforce any unique name requirements
00794  * in a section.
00795  *
00796  * Requires:
00797  *
00798  *\li   'msg' be valid, and be a renderable message.
00799  *
00800  *\li   'name' be a valid absolute name.
00801  *
00802  *\li   'section' be a named section.
00803  */
00804 
00805 void
00806 dns_message_removename(dns_message_t *msg, dns_name_t *name,
00807                        dns_section_t section);
00808 /*%<
00809  * Remove a existing name from a given section.
00810  *
00811  * It is the caller's responsibility to ensure the name is part of the
00812  * given section.
00813  *
00814  * Requires:
00815  *
00816  *\li   'msg' be valid, and be a renderable message.
00817  *
00818  *\li   'name' be a valid absolute name.
00819  *
00820  *\li   'section' be a named section.
00821  */
00822 
00823 
00824 /*
00825  * LOANOUT FUNCTIONS
00826  *
00827  * Each of these functions loan a particular type of data to the caller.
00828  * The storage for these will vanish when the message is destroyed or
00829  * reset, and must NOT be used after these operations.
00830  */
00831 
00832 isc_result_t
00833 dns_message_gettempname(dns_message_t *msg, dns_name_t **item);
00834 /*%<
00835  * Return a name that can be used for any temporary purpose, including
00836  * inserting into the message's linked lists.  The name must be returned
00837  * to the message code using dns_message_puttempname() or inserted into
00838  * one of the message's sections before the message is destroyed.
00839  *
00840  * It is the caller's responsibility to initialize this name.
00841  *
00842  * Requires:
00843  *\li   msg be a valid message
00844  *
00845  *\li   item != NULL && *item == NULL
00846  *
00847  * Returns:
00848  *\li   #ISC_R_SUCCESS          -- All is well.
00849  *\li   #ISC_R_NOMEMORY         -- No item can be allocated.
00850  */
00851 
00852 isc_result_t
00853 dns_message_gettempoffsets(dns_message_t *msg, dns_offsets_t **item);
00854 /*%<
00855  * Return an offsets array that can be used for any temporary purpose,
00856  * such as attaching to a temporary name.  The offsets will be freed
00857  * when the message is destroyed or reset.
00858  *
00859  * Requires:
00860  *\li   msg be a valid message
00861  *
00862  *\li   item != NULL && *item == NULL
00863  *
00864  * Returns:
00865  *\li   #ISC_R_SUCCESS          -- All is well.
00866  *\li   #ISC_R_NOMEMORY         -- No item can be allocated.
00867  */
00868 
00869 isc_result_t
00870 dns_message_gettemprdata(dns_message_t *msg, dns_rdata_t **item);
00871 /*%<
00872  * Return a rdata that can be used for any temporary purpose, including
00873  * inserting into the message's linked lists.  The rdata will be freed
00874  * when the message is destroyed or reset.
00875  *
00876  * Requires:
00877  *\li   msg be a valid message
00878  *
00879  *\li   item != NULL && *item == NULL
00880  *
00881  * Returns:
00882  *\li   #ISC_R_SUCCESS          -- All is well.
00883  *\li   #ISC_R_NOMEMORY         -- No item can be allocated.
00884  */
00885 
00886 isc_result_t
00887 dns_message_gettemprdataset(dns_message_t *msg, dns_rdataset_t **item);
00888 /*%<
00889  * Return a rdataset that can be used for any temporary purpose, including
00890  * inserting into the message's linked lists. The name must be returned
00891  * to the message code using dns_message_puttempname() or inserted into
00892  * one of the message's sections before the message is destroyed.
00893  *
00894  * Requires:
00895  *\li   msg be a valid message
00896  *
00897  *\li   item != NULL && *item == NULL
00898  *
00899  * Returns:
00900  *\li   #ISC_R_SUCCESS          -- All is well.
00901  *\li   #ISC_R_NOMEMORY         -- No item can be allocated.
00902  */
00903 
00904 isc_result_t
00905 dns_message_gettemprdatalist(dns_message_t *msg, dns_rdatalist_t **item);
00906 /*%<
00907  * Return a rdatalist that can be used for any temporary purpose, including
00908  * inserting into the message's linked lists.  The rdatalist will be
00909  * destroyed when the message is destroyed or reset.
00910  *
00911  * Requires:
00912  *\li   msg be a valid message
00913  *
00914  *\li   item != NULL && *item == NULL
00915  *
00916  * Returns:
00917  *\li   #ISC_R_SUCCESS          -- All is well.
00918  *\li   #ISC_R_NOMEMORY         -- No item can be allocated.
00919  */
00920 
00921 void
00922 dns_message_puttempname(dns_message_t *msg, dns_name_t **item);
00923 /*%<
00924  * Return a borrowed name to the message's name free list.
00925  *
00926  * Requires:
00927  *\li   msg be a valid message
00928  *
00929  *\li   item != NULL && *item point to a name returned by
00930  *      dns_message_gettempname()
00931  *
00932  * Ensures:
00933  *\li   *item == NULL
00934  */
00935 
00936 void
00937 dns_message_puttemprdata(dns_message_t *msg, dns_rdata_t **item);
00938 /*%<
00939  * Return a borrowed rdata to the message's rdata free list.
00940  *
00941  * Requires:
00942  *\li   msg be a valid message
00943  *
00944  *\li   item != NULL && *item point to a rdata returned by
00945  *      dns_message_gettemprdata()
00946  *
00947  * Ensures:
00948  *\li   *item == NULL
00949  */
00950 
00951 void
00952 dns_message_puttemprdataset(dns_message_t *msg, dns_rdataset_t **item);
00953 /*%<
00954  * Return a borrowed rdataset to the message's rdataset free list.
00955  *
00956  * Requires:
00957  *\li   msg be a valid message
00958  *
00959  *\li   item != NULL && *item point to a rdataset returned by
00960  *      dns_message_gettemprdataset()
00961  *
00962  * Ensures:
00963  *\li   *item == NULL
00964  */
00965 
00966 void
00967 dns_message_puttemprdatalist(dns_message_t *msg, dns_rdatalist_t **item);
00968 /*%<
00969  * Return a borrowed rdatalist to the message's rdatalist free list.
00970  *
00971  * Requires:
00972  *\li   msg be a valid message
00973  *
00974  *\li   item != NULL && *item point to a rdatalist returned by
00975  *      dns_message_gettemprdatalist()
00976  *
00977  * Ensures:
00978  *\li   *item == NULL
00979  */
00980 
00981 isc_result_t
00982 dns_message_peekheader(isc_buffer_t *source, dns_messageid_t *idp,
00983                        unsigned int *flagsp);
00984 /*%<
00985  * Assume the remaining region of "source" is a DNS message.  Peek into
00986  * it and fill in "*idp" with the message id, and "*flagsp" with the flags.
00987  *
00988  * Requires:
00989  *
00990  *\li   source != NULL
00991  *
00992  * Ensures:
00993  *
00994  *\li   if (idp != NULL) *idp == message id.
00995  *
00996  *\li   if (flagsp != NULL) *flagsp == message flags.
00997  *
00998  * Returns:
00999  *
01000  *\li   #ISC_R_SUCCESS          -- all is well.
01001  *
01002  *\li   #ISC_R_UNEXPECTEDEND    -- buffer doesn't contain enough for a header.
01003  */
01004 
01005 isc_result_t
01006 dns_message_reply(dns_message_t *msg, isc_boolean_t want_question_section);
01007 /*%<
01008  * Start formatting a reply to the query in 'msg'.
01009  *
01010  * Requires:
01011  *
01012  *\li   'msg' is a valid message with parsing intent, and contains a query.
01013  *
01014  * Ensures:
01015  *
01016  *\li   The message will have a rendering intent.  If 'want_question_section'
01017  *      is true, the message opcode is query or notify, and the question
01018  *      section is present and properly formatted, then the question section
01019  *      will be included in the reply.  All other sections will be cleared.
01020  *      The QR flag will be set, the RD flag will be preserved, and all other
01021  *      flags will be cleared.
01022  *
01023  * Returns:
01024  *
01025  *\li   #ISC_R_SUCCESS          -- all is well.
01026  *
01027  *\li   #DNS_R_FORMERR          -- the header or question section of the
01028  *                                 message is invalid, replying is impossible.
01029  *                                 If DNS_R_FORMERR is returned when
01030  *                                 want_question_section is ISC_FALSE, then
01031  *                                 it's the header section that's bad;
01032  *                                 otherwise either of the header or question
01033  *                                 sections may be bad.
01034  */
01035 
01036 dns_rdataset_t *
01037 dns_message_getopt(dns_message_t *msg);
01038 /*%<
01039  * Get the OPT record for 'msg'.
01040  *
01041  * Requires:
01042  *
01043  *\li   'msg' is a valid message.
01044  *
01045  * Returns:
01046  *
01047  *\li   The OPT rdataset of 'msg', or NULL if there isn't one.
01048  */
01049 
01050 isc_result_t
01051 dns_message_setopt(dns_message_t *msg, dns_rdataset_t *opt);
01052 /*%<
01053  * Set the OPT record for 'msg'.
01054  *
01055  * Requires:
01056  *
01057  *\li   'msg' is a valid message with rendering intent
01058  *      and no sections have been rendered.
01059  *
01060  *\li   'opt' is a valid OPT record.
01061  *
01062  * Ensures:
01063  *
01064  *\li   The OPT record has either been freed or ownership of it has
01065  *      been transferred to the message.
01066  *
01067  *\li   If ISC_R_SUCCESS was returned, the OPT record will be rendered
01068  *      when dns_message_renderend() is called.
01069  *
01070  * Returns:
01071  *
01072  *\li   #ISC_R_SUCCESS          -- all is well.
01073  *
01074  *\li   #ISC_R_NOSPACE          -- there is no space for the OPT record.
01075  */
01076 
01077 dns_rdataset_t *
01078 dns_message_gettsig(dns_message_t *msg, dns_name_t **owner);
01079 /*%<
01080  * Get the TSIG record and owner for 'msg'.
01081  *
01082  * Requires:
01083  *
01084  *\li   'msg' is a valid message.
01085  *\li   'owner' is NULL or *owner is NULL.
01086  *
01087  * Returns:
01088  *
01089  *\li   The TSIG rdataset of 'msg', or NULL if there isn't one.
01090  *
01091  * Ensures:
01092  *
01093  * \li  If 'owner' is not NULL, it will point to the owner name.
01094  */
01095 
01096 isc_result_t
01097 dns_message_settsigkey(dns_message_t *msg, dns_tsigkey_t *key);
01098 /*%<
01099  * Set the tsig key for 'msg'.  This is only necessary for when rendering a
01100  * query or parsing a response.  The key (if non-NULL) is attached to, and
01101  * will be detached when the message is destroyed.
01102  *
01103  * Requires:
01104  *
01105  *\li   'msg' is a valid message with rendering intent,
01106  *      dns_message_renderbegin() has been called, and no sections have been
01107  *      rendered.
01108  *\li   'key' is a valid tsig key or NULL.
01109  *
01110  * Returns:
01111  *
01112  *\li   #ISC_R_SUCCESS          -- all is well.
01113  *
01114  *\li   #ISC_R_NOSPACE          -- there is no space for the TSIG record.
01115  */
01116 
01117 dns_tsigkey_t *
01118 dns_message_gettsigkey(dns_message_t *msg);
01119 /*%<
01120  * Gets the tsig key for 'msg'.
01121  *
01122  * Requires:
01123  *
01124  *\li   'msg' is a valid message
01125  */
01126 
01127 isc_result_t
01128 dns_message_setquerytsig(dns_message_t *msg, isc_buffer_t *querytsig);
01129 /*%<
01130  * Indicates that 'querytsig' is the TSIG from the signed query for which
01131  * 'msg' is the response.  This is also used for chained TSIGs in TCP
01132  * responses.
01133  *
01134  * Requires:
01135  *
01136  *\li   'querytsig' is a valid buffer as returned by dns_message_getquerytsig()
01137  *      or NULL
01138  *
01139  *\li   'msg' is a valid message
01140  *
01141  * Returns:
01142  *
01143  *\li   #ISC_R_SUCCESS
01144  *\li   #ISC_R_NOMEMORY
01145  */
01146 
01147 isc_result_t
01148 dns_message_getquerytsig(dns_message_t *msg, isc_mem_t *mctx,
01149                          isc_buffer_t **querytsig);
01150 /*%<
01151  * Gets the tsig from the TSIG from the signed query 'msg'.  This is also used
01152  * for chained TSIGs in TCP responses.  Unlike dns_message_gettsig, this makes
01153  * a copy of the data, so can be used if the message is destroyed.
01154  *
01155  * Requires:
01156  *
01157  *\li   'msg' is a valid signed message
01158  *\li   'mctx' is a valid memory context
01159  *\li   querytsig != NULL && *querytsig == NULL
01160  *
01161  * Returns:
01162  *
01163  *\li   #ISC_R_SUCCESS
01164  *\li   #ISC_R_NOMEMORY
01165  *
01166  * Ensures:
01167  *\li   'tsig' points to NULL or an allocated buffer which must be freed
01168  *      by the caller.
01169  */
01170 
01171 dns_rdataset_t *
01172 dns_message_getsig0(dns_message_t *msg, dns_name_t **owner);
01173 /*%<
01174  * Get the SIG(0) record and owner for 'msg'.
01175  *
01176  * Requires:
01177  *
01178  *\li   'msg' is a valid message.
01179  *\li   'owner' is NULL or *owner is NULL.
01180  *
01181  * Returns:
01182  *
01183  *\li   The SIG(0) rdataset of 'msg', or NULL if there isn't one.
01184  *
01185  * Ensures:
01186  *
01187  * \li  If 'owner' is not NULL, it will point to the owner name.
01188  */
01189 
01190 isc_result_t
01191 dns_message_setsig0key(dns_message_t *msg, dst_key_t *key);
01192 /*%<
01193  * Set the SIG(0) key for 'msg'.
01194  *
01195  * Requires:
01196  *
01197  *\li   'msg' is a valid message with rendering intent,
01198  *      dns_message_renderbegin() has been called, and no sections have been
01199  *      rendered.
01200  *\li   'key' is a valid sig key or NULL.
01201  *
01202  * Returns:
01203  *
01204  *\li   #ISC_R_SUCCESS          -- all is well.
01205  *
01206  *\li   #ISC_R_NOSPACE          -- there is no space for the SIG(0) record.
01207  */
01208 
01209 dst_key_t *
01210 dns_message_getsig0key(dns_message_t *msg);
01211 /*%<
01212  * Gets the SIG(0) key for 'msg'.
01213  *
01214  * Requires:
01215  *
01216  *\li   'msg' is a valid message
01217  */
01218 
01219 void
01220 dns_message_takebuffer(dns_message_t *msg, isc_buffer_t **buffer);
01221 /*%<
01222  * Give the *buffer to the message code to clean up when it is no
01223  * longer needed.  This is usually when the message is reset or
01224  * destroyed.
01225  *
01226  * Requires:
01227  *
01228  *\li   msg be a valid message.
01229  *
01230  *\li   buffer != NULL && *buffer is a valid isc_buffer_t, which was
01231  *      dynamically allocated via isc_buffer_allocate().
01232  */
01233 
01234 isc_result_t
01235 dns_message_signer(dns_message_t *msg, dns_name_t *signer);
01236 /*%<
01237  * If this message was signed, return the identity of the signer.
01238  * Unless ISC_R_NOTFOUND is returned, signer will reflect the name of the
01239  * key that signed the message.
01240  *
01241  * Requires:
01242  *
01243  *\li   msg is a valid parsed message.
01244  *\li   signer is a valid name
01245  *
01246  * Returns:
01247  *
01248  *\li   #ISC_R_SUCCESS          - the message was signed, and *signer
01249  *                                contains the signing identity
01250  *
01251  *\li   #ISC_R_NOTFOUND         - no TSIG or SIG(0) record is present in the
01252  *                                message
01253  *
01254  *\li   #DNS_R_TSIGVERIFYFAILURE        - the message was signed by a TSIG, but the
01255  *                                signature failed to verify
01256  *
01257  *\li   #DNS_R_TSIGERRORSET     - the message was signed by a TSIG and
01258  *                                verified, but the query was rejected by
01259  *                                the server
01260  *
01261  *\li   #DNS_R_NOIDENTITY       - the message was signed by a TSIG and
01262  *                                verified, but the key has no identity since
01263  *                                it was generated by an unsigned TKEY process
01264  *
01265  *\li   #DNS_R_SIGINVALID       - the message was signed by a SIG(0), but
01266  *                                the signature failed to verify
01267  *
01268  *\li   #DNS_R_NOTVERIFIEDYET   - the message was signed by a TSIG or SIG(0),
01269  *                                but the signature has not been verified yet
01270  */
01271 
01272 isc_result_t
01273 dns_message_checksig(dns_message_t *msg, dns_view_t *view);
01274 /*%<
01275  * If this message was signed, verify the signature.
01276  *
01277  * Requires:
01278  *
01279  *\li   msg is a valid parsed message.
01280  *\li   view is a valid view or NULL
01281  *
01282  * Returns:
01283  *
01284  *\li   #ISC_R_SUCCESS          - the message was unsigned, or the message
01285  *                                was signed correctly.
01286  *
01287  *\li   #DNS_R_EXPECTEDTSIG     - A TSIG was expected, but not seen
01288  *\li   #DNS_R_UNEXPECTEDTSIG   - A TSIG was seen but not expected
01289  *\li   #DNS_R_TSIGVERIFYFAILURE - The TSIG failed to verify
01290  */
01291 
01292 isc_result_t
01293 dns_message_rechecksig(dns_message_t *msg, dns_view_t *view);
01294 /*%<
01295  * Reset the signature state and then if the message was signed,
01296  * verify the message.
01297  *
01298  * Requires:
01299  *
01300  *\li   msg is a valid parsed message.
01301  *\li   view is a valid view or NULL
01302  *
01303  * Returns:
01304  *
01305  *\li   #ISC_R_SUCCESS          - the message was unsigned, or the message
01306  *                                was signed correctly.
01307  *
01308  *\li   #DNS_R_EXPECTEDTSIG     - A TSIG was expected, but not seen
01309  *\li   #DNS_R_UNEXPECTEDTSIG   - A TSIG was seen but not expected
01310  *\li   #DNS_R_TSIGVERIFYFAILURE - The TSIG failed to verify
01311  */
01312 
01313 void
01314 dns_message_resetsig(dns_message_t *msg);
01315 /*%<
01316  * Reset the signature state.
01317  *
01318  * Requires:
01319  *\li   'msg' is a valid parsed message.
01320  */
01321 
01322 isc_region_t *
01323 dns_message_getrawmessage(dns_message_t *msg);
01324 /*%<
01325  * Retrieve the raw message in compressed wire format.  The message must
01326  * have been successfully parsed for it to have been saved.
01327  *
01328  * Requires:
01329  *\li   msg is a valid parsed message.
01330  *
01331  * Returns:
01332  *\li   NULL    if there is no saved message.
01333  *      a pointer to a region which refers the dns message.
01334  */
01335 
01336 void
01337 dns_message_setsortorder(dns_message_t *msg, dns_rdatasetorderfunc_t order,
01338                          const void *order_arg);
01339 /*%<
01340  * Define the order in which RR sets get rendered by
01341  * dns_message_rendersection() to be the ascending order
01342  * defined by the integer value returned by 'order' when
01343  * given each RR and 'arg' as arguments.  If 'order' and
01344  * 'order_arg' are NULL, a default order is used.
01345  *
01346  * Requires:
01347  *\li   msg be a valid message.
01348  *\li   order_arg is NULL if and only if order is NULL.
01349  */
01350 
01351 void
01352 dns_message_settimeadjust(dns_message_t *msg, int timeadjust);
01353 /*%<
01354  * Adjust the time used to sign/verify a message by timeadjust.
01355  * Currently only TSIG.
01356  *
01357  * Requires:
01358  *\li   msg be a valid message.
01359  */
01360 
01361 int
01362 dns_message_gettimeadjust(dns_message_t *msg);
01363 /*%<
01364  * Return the current time adjustment.
01365  *
01366  * Requires:
01367  *\li   msg be a valid message.
01368  */
01369 
01370 void
01371 dns_message_logpacket(dns_message_t *message, const char *description,
01372                       isc_logcategory_t *category, isc_logmodule_t *module,
01373                       int level, isc_mem_t *mctx);
01374 void
01375 dns_message_logpacket2(dns_message_t *message,
01376                        const char *description, isc_sockaddr_t *address,
01377                        isc_logcategory_t *category, isc_logmodule_t *module,
01378                        int level, isc_mem_t *mctx);
01379 void
01380 dns_message_logfmtpacket(dns_message_t *message, const char *description,
01381                          isc_logcategory_t *category, isc_logmodule_t *module,
01382                          const dns_master_style_t *style, int level,
01383                          isc_mem_t *mctx);
01384 void
01385 dns_message_logfmtpacket2(dns_message_t *message,
01386                           const char *description, isc_sockaddr_t *address,
01387                           isc_logcategory_t *category, isc_logmodule_t *module,
01388                           const dns_master_style_t *style, int level,
01389                           isc_mem_t *mctx);
01390 /*%<
01391  * Log 'message' at the specified logging parameters.
01392  *
01393  * For dns_message_logpacket and dns_message_logfmtpacket expect the
01394  * 'description' to end in a newline.
01395  *
01396  * For dns_message_logpacket2 and dns_message_logfmtpacket2
01397  * 'description' will be emitted at the start of the message followed
01398  * by the formatted address and a newline.
01399  *
01400  * Requires:
01401  * \li   message be a valid.
01402  * \li   description to be non NULL.
01403  * \li   address to be non NULL.
01404  * \li   category to be valid.
01405  * \li   module to be valid.
01406  * \li   style to be valid.
01407  * \li   mctx to be a valid.
01408  */
01409 
01410 isc_result_t
01411 dns_message_buildopt(dns_message_t *msg, dns_rdataset_t **opt,
01412                      unsigned int version, isc_uint16_t udpsize,
01413                      unsigned int flags, dns_ednsopt_t *ednsopts, size_t count);
01414 /*%<
01415  * Built a opt record.
01416  *
01417  * Requires:
01418  * \li   msg be a valid message.
01419  * \li   opt to be a non NULL and *opt to be NULL.
01420  *
01421  * Returns:
01422  * \li   ISC_R_SUCCESS on success.
01423  * \li   ISC_R_NOMEMORY
01424  * \li   ISC_R_NOSPACE
01425  * \li   other.
01426  */
01427 
01428 ISC_LANG_ENDDECLS
01429 
01430 #endif /* DNS_MESSAGE_H */

Generated on Tue Apr 28 17:40:57 2015 by Doxygen 1.5.4 for BIND9 Internals 9.11.0pre-alpha