/contrib/bind9/lib/dns/include/dns/message.h
C Header | 1355 lines | 248 code | 96 blank | 1011 comment | 0 complexity | 1d2e4254d52bc1f222a3d04f6632d130 MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
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 */