PageRenderTime 95ms CodeModel.GetById 68ms app.highlight 18ms RepoModel.GetById 2ms app.codeStats 0ms

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

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