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