1 /* 2 * Copyright (C) 2004-2007, 2009-2012, 2015, 2016 Internet Systems Consortium, Inc. ("ISC") 3 * Copyright (C) 1998-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: name.h,v 1.137 2011/01/13 04:59:26 tbox Exp $ */ 19 20 #ifndef DNS_NAME_H 21 #define DNS_NAME_H 1 22 23 /***** 24 ***** Module Info 25 *****/ 26 27 /*! \file dns/name.h 28 * \brief 29 * Provides facilities for manipulating DNS names and labels, including 30 * conversions to and from wire format and text format. 31 * 32 * Given the large number of names possible in a nameserver, and because 33 * names occur in rdata, it was important to come up with a very efficient 34 * way of storing name data, but at the same time allow names to be 35 * manipulated. The decision was to store names in uncompressed wire format, 36 * and not to make them fully abstracted objects; i.e. certain parts of the 37 * server know names are stored that way. This saves a lot of memory, and 38 * makes adding names to messages easy. Having much of the server know 39 * the representation would be perilous, and we certainly don't want each 40 * user of names to be manipulating such a low-level structure. This is 41 * where the Names and Labels module comes in. The module allows name or 42 * label handles to be created and attached to uncompressed wire format 43 * regions. All name operations and conversions are done through these 44 * handles. 45 * 46 * MP: 47 *\li Clients of this module must impose any required synchronization. 48 * 49 * Reliability: 50 *\li This module deals with low-level byte streams. Errors in any of 51 * the functions are likely to crash the server or corrupt memory. 52 * 53 * Resources: 54 *\li None. 55 * 56 * Security: 57 * 58 *\li *** WARNING *** 59 * 60 *\li dns_name_fromwire() deals with raw network data. An error in 61 * this routine could result in the failure or hijacking of the server. 62 * 63 * Standards: 64 *\li RFC1035 65 *\li Draft EDNS0 (0) 66 *\li Draft Binary Labels (2) 67 * 68 */ 69 70 /*** 71 *** Imports 72 ***/ 73 74 #include <stdio.h> 75 76 #include <isc/boolean.h> 77 #include <isc/lang.h> 78 #include <isc/magic.h> 79 #include <isc/region.h> /* Required for storage size of dns_label_t. */ 80 81 #include <dns/types.h> 82 83 ISC_LANG_BEGINDECLS 84 85 /***** 86 ***** Labels 87 ***** 88 ***** A 'label' is basically a region. It contains one DNS wire format 89 ***** label of type 00 (ordinary). 90 *****/ 91 92 /***** 93 ***** Names 94 ***** 95 ***** A 'name' is a handle to a binary region. It contains a sequence of one 96 ***** or more DNS wire format labels of type 00 (ordinary). 97 ***** Note that all names are not required to end with the root label, 98 ***** as they are in the actual DNS wire protocol. 99 *****/ 100 101 /*** 102 *** Types 103 ***/ 104 105 /*% 106 * Clients are strongly discouraged from using this type directly, with 107 * the exception of the 'link' and 'list' fields which may be used directly 108 * for whatever purpose the client desires. 109 */ 110 struct dns_name { 111 unsigned int magic; 112 unsigned char * ndata; 113 unsigned int length; 114 unsigned int labels; 115 unsigned int attributes; 116 unsigned char * offsets; 117 isc_buffer_t * buffer; 118 ISC_LINK(dns_name_t) link; 119 ISC_LIST(dns_rdataset_t) list; 120 }; 121 122 #define DNS_NAME_MAGIC ISC_MAGIC('D','N','S','n') 123 124 #define DNS_NAMEATTR_ABSOLUTE 0x00000001 125 #define DNS_NAMEATTR_READONLY 0x00000002 126 #define DNS_NAMEATTR_DYNAMIC 0x00000004 127 #define DNS_NAMEATTR_DYNOFFSETS 0x00000008 128 #define DNS_NAMEATTR_NOCOMPRESS 0x00000010 129 /* 130 * Attributes below 0x0100 reserved for name.c usage. 131 */ 132 #define DNS_NAMEATTR_CACHE 0x00000100 /*%< Used by resolver. */ 133 #define DNS_NAMEATTR_ANSWER 0x00000200 /*%< Used by resolver. */ 134 #define DNS_NAMEATTR_NCACHE 0x00000400 /*%< Used by resolver. */ 135 #define DNS_NAMEATTR_CHAINING 0x00000800 /*%< Used by resolver. */ 136 #define DNS_NAMEATTR_CHASE 0x00001000 /*%< Used by resolver. */ 137 #define DNS_NAMEATTR_WILDCARD 0x00002000 /*%< Used by server. */ 138 #define DNS_NAMEATTR_PREREQUISITE 0x00004000 /*%< Used by client. */ 139 #define DNS_NAMEATTR_UPDATE 0x00008000 /*%< Used by client. */ 140 #define DNS_NAMEATTR_HASUPDATEREC 0x00010000 /*%< Used by client. */ 141 142 /* 143 * Various flags. 144 */ 145 #define DNS_NAME_DOWNCASE 0x0001 146 #define DNS_NAME_CHECKNAMES 0x0002 /*%< Used by rdata. */ 147 #define DNS_NAME_CHECKNAMESFAIL 0x0004 /*%< Used by rdata. */ 148 #define DNS_NAME_CHECKREVERSE 0x0008 /*%< Used by rdata. */ 149 #define DNS_NAME_CHECKMX 0x0010 /*%< Used by rdata. */ 150 #define DNS_NAME_CHECKMXFAIL 0x0020 /*%< Used by rdata. */ 151 152 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_rootname; 153 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_wildcardname; 154 155 /*% 156 * Standard size of a wire format name 157 */ 158 #define DNS_NAME_MAXWIRE 255 159 160 /* 161 * Text output filter procedure. 162 * 'target' is the buffer to be converted. The region to be converted 163 * is from 'buffer'->base + 'used_org' to the end of the used region. 164 */ 165 typedef isc_result_t (*dns_name_totextfilter_t)(isc_buffer_t *target, 166 unsigned int used_org, 167 isc_boolean_t absolute); 168 169 /*** 170 *** Initialization 171 ***/ 172 173 void 174 dns_name_init(dns_name_t *name, unsigned char *offsets); 175 /*%< 176 * Initialize 'name'. 177 * 178 * Notes: 179 * \li 'offsets' is never required to be non-NULL, but specifying a 180 * dns_offsets_t for 'offsets' will improve the performance of most 181 * name operations if the name is used more than once. 182 * 183 * Requires: 184 * \li 'name' is not NULL and points to a struct dns_name. 185 * 186 * \li offsets == NULL or offsets is a dns_offsets_t. 187 * 188 * Ensures: 189 * \li 'name' is a valid name. 190 * \li dns_name_countlabels(name) == 0 191 * \li dns_name_isabsolute(name) == ISC_FALSE 192 */ 193 194 void 195 dns_name_reset(dns_name_t *name); 196 /*%< 197 * Reinitialize 'name'. 198 * 199 * Notes: 200 * \li This function distinguishes itself from dns_name_init() in two 201 * key ways: 202 * 203 * \li + If any buffer is associated with 'name' (via dns_name_setbuffer() 204 * or by being part of a dns_fixedname_t) the link to the buffer 205 * is retained but the buffer itself is cleared. 206 * 207 * \li + Of the attributes associated with 'name', all are retained except 208 * DNS_NAMEATTR_ABSOLUTE. 209 * 210 * Requires: 211 * \li 'name' is a valid name. 212 * 213 * Ensures: 214 * \li 'name' is a valid name. 215 * \li dns_name_countlabels(name) == 0 216 * \li dns_name_isabsolute(name) == ISC_FALSE 217 */ 218 219 void 220 dns_name_invalidate(dns_name_t *name); 221 /*%< 222 * Make 'name' invalid. 223 * 224 * Requires: 225 * \li 'name' is a valid name. 226 * 227 * Ensures: 228 * \li If assertion checking is enabled, future attempts to use 'name' 229 * without initializing it will cause an assertion failure. 230 * 231 * \li If the name had a dedicated buffer, that association is ended. 232 */ 233 234 235 /*** 236 *** Dedicated Buffers 237 ***/ 238 239 void 240 dns_name_setbuffer(dns_name_t *name, isc_buffer_t *buffer); 241 /*%< 242 * Dedicate a buffer for use with 'name'. 243 * 244 * Notes: 245 * \li Specification of a target buffer in dns_name_fromwire(), 246 * dns_name_fromtext(), and dns_name_concatenate() is optional if 247 * 'name' has a dedicated buffer. 248 * 249 * \li The caller must not write to buffer until the name has been 250 * invalidated or is otherwise known not to be in use. 251 * 252 * \li If buffer is NULL and the name previously had a dedicated buffer, 253 * than that buffer is no longer dedicated to use with this name. 254 * The caller is responsible for ensuring that the storage used by 255 * the name remains valid. 256 * 257 * Requires: 258 * \li 'name' is a valid name. 259 * 260 * \li 'buffer' is a valid binary buffer and 'name' doesn't have a 261 * dedicated buffer already, or 'buffer' is NULL. 262 */ 263 264 isc_boolean_t 265 dns_name_hasbuffer(const dns_name_t *name); 266 /*%< 267 * Does 'name' have a dedicated buffer? 268 * 269 * Requires: 270 * \li 'name' is a valid name. 271 * 272 * Returns: 273 * \li ISC_TRUE 'name' has a dedicated buffer. 274 * \li ISC_FALSE 'name' does not have a dedicated buffer. 275 */ 276 277 /*** 278 *** Properties 279 ***/ 280 281 isc_boolean_t 282 dns_name_isabsolute(const dns_name_t *name); 283 /*%< 284 * Does 'name' end in the root label? 285 * 286 * Requires: 287 * \li 'name' is a valid name 288 * 289 * Returns: 290 * \li TRUE The last label in 'name' is the root label. 291 * \li FALSE The last label in 'name' is not the root label. 292 */ 293 294 isc_boolean_t 295 dns_name_iswildcard(const dns_name_t *name); 296 /*%< 297 * Is 'name' a wildcard name? 298 * 299 * Requires: 300 * \li 'name' is a valid name 301 * 302 * \li dns_name_countlabels(name) > 0 303 * 304 * Returns: 305 * \li TRUE The least significant label of 'name' is '*'. 306 * \li FALSE The least significant label of 'name' is not '*'. 307 */ 308 309 unsigned int 310 dns_name_hash(dns_name_t *name, isc_boolean_t case_sensitive); 311 /*%< 312 * Provide a hash value for 'name'. 313 * 314 * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in 315 * case will have the same hash value. 316 * 317 * Requires: 318 * \li 'name' is a valid name 319 * 320 * Returns: 321 * \li A hash value 322 */ 323 324 unsigned int 325 dns_name_fullhash(dns_name_t *name, isc_boolean_t case_sensitive); 326 /*%< 327 * Provide a hash value for 'name'. Unlike dns_name_hash(), this function 328 * always takes into account of the entire name to calculate the hash value. 329 * 330 * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in 331 * case will have the same hash value. 332 * 333 * Requires: 334 *\li 'name' is a valid name 335 * 336 * Returns: 337 *\li A hash value 338 */ 339 340 unsigned int 341 dns_name_hashbylabel(dns_name_t *name, isc_boolean_t case_sensitive); 342 /*%< 343 * Provide a hash value for 'name', where the hash value is the sum 344 * of the hash values of each label. 345 * 346 * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in 347 * case will have the same hash value. 348 * 349 * Requires: 350 *\li 'name' is a valid name 351 * 352 * Returns: 353 *\li A hash value 354 */ 355 356 /* 357 *** Comparisons 358 ***/ 359 360 dns_namereln_t 361 dns_name_fullcompare(const dns_name_t *name1, const dns_name_t *name2, 362 int *orderp, unsigned int *nlabelsp); 363 /*%< 364 * Determine the relative ordering under the DNSSEC order relation of 365 * 'name1' and 'name2', and also determine the hierarchical 366 * relationship of the names. 367 * 368 * Note: It makes no sense for one of the names to be relative and the 369 * other absolute. If both names are relative, then to be meaningfully 370 * compared the caller must ensure that they are both relative to the 371 * same domain. 372 * 373 * Requires: 374 *\li 'name1' is a valid name 375 * 376 *\li dns_name_countlabels(name1) > 0 377 * 378 *\li 'name2' is a valid name 379 * 380 *\li dns_name_countlabels(name2) > 0 381 * 382 *\li orderp and nlabelsp are valid pointers. 383 * 384 *\li Either name1 is absolute and name2 is absolute, or neither is. 385 * 386 * Ensures: 387 * 388 *\li *orderp is < 0 if name1 < name2, 0 if name1 = name2, > 0 if 389 * name1 > name2. 390 * 391 *\li *nlabelsp is the number of common significant labels. 392 * 393 * Returns: 394 *\li dns_namereln_none There's no hierarchical relationship 395 * between name1 and name2. 396 *\li dns_namereln_contains name1 properly contains name2; i.e. 397 * name2 is a proper subdomain of name1. 398 *\li dns_namereln_subdomain name1 is a proper subdomain of name2. 399 *\li dns_namereln_equal name1 and name2 are equal. 400 *\li dns_namereln_commonancestor name1 and name2 share a common 401 * ancestor. 402 */ 403 404 int 405 dns_name_compare(const dns_name_t *name1, const dns_name_t *name2); 406 /*%< 407 * Determine the relative ordering under the DNSSEC order relation of 408 * 'name1' and 'name2'. 409 * 410 * Note: It makes no sense for one of the names to be relative and the 411 * other absolute. If both names are relative, then to be meaningfully 412 * compared the caller must ensure that they are both relative to the 413 * same domain. 414 * 415 * Requires: 416 * \li 'name1' is a valid name 417 * 418 * \li 'name2' is a valid name 419 * 420 * \li Either name1 is absolute and name2 is absolute, or neither is. 421 * 422 * Returns: 423 * \li < 0 'name1' is less than 'name2' 424 * \li 0 'name1' is equal to 'name2' 425 * \li > 0 'name1' is greater than 'name2' 426 */ 427 428 isc_boolean_t 429 dns_name_equal(const dns_name_t *name1, const dns_name_t *name2); 430 /*%< 431 * Are 'name1' and 'name2' equal? 432 * 433 * Notes: 434 * \li Because it only needs to test for equality, dns_name_equal() can be 435 * significantly faster than dns_name_fullcompare() or dns_name_compare(). 436 * 437 * \li Offsets tables are not used in the comparision. 438 * 439 * \li It makes no sense for one of the names to be relative and the 440 * other absolute. If both names are relative, then to be meaningfully 441 * compared the caller must ensure that they are both relative to the 442 * same domain. 443 * 444 * Requires: 445 * \li 'name1' is a valid name 446 * 447 * \li 'name2' is a valid name 448 * 449 * \li Either name1 is absolute and name2 is absolute, or neither is. 450 * 451 * Returns: 452 * \li ISC_TRUE 'name1' and 'name2' are equal 453 * \li ISC_FALSE 'name1' and 'name2' are not equal 454 */ 455 456 isc_boolean_t 457 dns_name_caseequal(const dns_name_t *name1, const dns_name_t *name2); 458 /*%< 459 * Case sensitive version of dns_name_equal(). 460 */ 461 462 int 463 dns_name_rdatacompare(const dns_name_t *name1, const dns_name_t *name2); 464 /*%< 465 * Compare two names as if they are part of rdata in DNSSEC canonical 466 * form. 467 * 468 * Requires: 469 * \li 'name1' is a valid absolute name 470 * 471 * \li dns_name_countlabels(name1) > 0 472 * 473 * \li 'name2' is a valid absolute name 474 * 475 * \li dns_name_countlabels(name2) > 0 476 * 477 * Returns: 478 * \li < 0 'name1' is less than 'name2' 479 * \li 0 'name1' is equal to 'name2' 480 * \li > 0 'name1' is greater than 'name2' 481 */ 482 483 isc_boolean_t 484 dns_name_issubdomain(const dns_name_t *name1, const dns_name_t *name2); 485 /*%< 486 * Is 'name1' a subdomain of 'name2'? 487 * 488 * Notes: 489 * \li name1 is a subdomain of name2 if name1 is contained in name2, or 490 * name1 equals name2. 491 * 492 * \li It makes no sense for one of the names to be relative and the 493 * other absolute. If both names are relative, then to be meaningfully 494 * compared the caller must ensure that they are both relative to the 495 * same domain. 496 * 497 * Requires: 498 * \li 'name1' is a valid name 499 * 500 * \li 'name2' is a valid name 501 * 502 * \li Either name1 is absolute and name2 is absolute, or neither is. 503 * 504 * Returns: 505 * \li TRUE 'name1' is a subdomain of 'name2' 506 * \li FALSE 'name1' is not a subdomain of 'name2' 507 */ 508 509 isc_boolean_t 510 dns_name_matcheswildcard(const dns_name_t *name, const dns_name_t *wname); 511 /*%< 512 * Does 'name' match the wildcard specified in 'wname'? 513 * 514 * Notes: 515 * \li name matches the wildcard specified in wname if all labels 516 * following the wildcard in wname are identical to the same number 517 * of labels at the end of name. 518 * 519 * \li It makes no sense for one of the names to be relative and the 520 * other absolute. If both names are relative, then to be meaningfully 521 * compared the caller must ensure that they are both relative to the 522 * same domain. 523 * 524 * Requires: 525 * \li 'name' is a valid name 526 * 527 * \li dns_name_countlabels(name) > 0 528 * 529 * \li 'wname' is a valid name 530 * 531 * \li dns_name_countlabels(wname) > 0 532 * 533 * \li dns_name_iswildcard(wname) is true 534 * 535 * \li Either name is absolute and wname is absolute, or neither is. 536 * 537 * Returns: 538 * \li TRUE 'name' matches the wildcard specified in 'wname' 539 * \li FALSE 'name' does not match the wildcard specified in 'wname' 540 */ 541 542 /*** 543 *** Labels 544 ***/ 545 546 unsigned int 547 dns_name_countlabels(const dns_name_t *name); 548 /*%< 549 * How many labels does 'name' have? 550 * 551 * Notes: 552 * \li In this case, as in other places, a 'label' is an ordinary label. 553 * 554 * Requires: 555 * \li 'name' is a valid name 556 * 557 * Ensures: 558 * \li The result is <= 128. 559 * 560 * Returns: 561 * \li The number of labels in 'name'. 562 */ 563 564 void 565 dns_name_getlabel(const dns_name_t *name, unsigned int n, dns_label_t *label); 566 /*%< 567 * Make 'label' refer to the 'n'th least significant label of 'name'. 568 * 569 * Notes: 570 * \li Numbering starts at 0. 571 * 572 * \li Given "rc.vix.com.", the label 0 is "rc", and label 3 is the 573 * root label. 574 * 575 * \li 'label' refers to the same memory as 'name', so 'name' must not 576 * be changed while 'label' is still in use. 577 * 578 * Requires: 579 * \li n < dns_name_countlabels(name) 580 */ 581 582 void 583 dns_name_getlabelsequence(const dns_name_t *source, unsigned int first, 584 unsigned int n, dns_name_t *target); 585 /*%< 586 * Make 'target' refer to the 'n' labels including and following 'first' 587 * in 'source'. 588 * 589 * Notes: 590 * \li Numbering starts at 0. 591 * 592 * \li Given "rc.vix.com.", the label 0 is "rc", and label 3 is the 593 * root label. 594 * 595 * \li 'target' refers to the same memory as 'source', so 'source' 596 * must not be changed while 'target' is still in use. 597 * 598 * Requires: 599 * \li 'source' and 'target' are valid names. 600 * 601 * \li first < dns_name_countlabels(name) 602 * 603 * \li first + n <= dns_name_countlabels(name) 604 */ 605 606 607 void 608 dns_name_clone(const dns_name_t *source, dns_name_t *target); 609 /*%< 610 * Make 'target' refer to the same name as 'source'. 611 * 612 * Notes: 613 * 614 * \li 'target' refers to the same memory as 'source', so 'source' 615 * must not be changed while 'target' is still in use. 616 * 617 * \li This call is functionally equivalent to: 618 * 619 * \code 620 * dns_name_getlabelsequence(source, 0, 621 * dns_name_countlabels(source), 622 * target); 623 * \endcode 624 * 625 * but is more efficient. Also, dns_name_clone() works even if 'source' 626 * is empty. 627 * 628 * Requires: 629 * 630 * \li 'source' is a valid name. 631 * 632 * \li 'target' is a valid name that is not read-only. 633 */ 634 635 /*** 636 *** Conversions 637 ***/ 638 639 void 640 dns_name_fromregion(dns_name_t *name, const isc_region_t *r); 641 /*%< 642 * Make 'name' refer to region 'r'. 643 * 644 * Note: 645 * \li If the conversion encounters a root label before the end of the 646 * region the conversion stops and the length is set to the length 647 * so far converted. A maximum of 255 bytes is converted. 648 * 649 * Requires: 650 * \li The data in 'r' is a sequence of one or more type 00 or type 01000001 651 * labels. 652 */ 653 654 void 655 dns_name_toregion(dns_name_t *name, isc_region_t *r); 656 /*%< 657 * Make 'r' refer to 'name'. 658 * 659 * Requires: 660 * 661 * \li 'name' is a valid name. 662 * 663 * \li 'r' is a valid region. 664 */ 665 666 isc_result_t 667 dns_name_fromwire(dns_name_t *name, isc_buffer_t *source, 668 dns_decompress_t *dctx, unsigned int options, 669 isc_buffer_t *target); 670 /*%< 671 * Copy the possibly-compressed name at source (active region) into target, 672 * decompressing it. 673 * 674 * Notes: 675 * \li Decompression policy is controlled by 'dctx'. 676 * 677 * \li If DNS_NAME_DOWNCASE is set, any uppercase letters in 'source' will be 678 * downcased when they are copied into 'target'. 679 * 680 * Security: 681 * 682 * \li *** WARNING *** 683 * 684 * \li This routine will often be used when 'source' contains raw network 685 * data. A programming error in this routine could result in a denial 686 * of service, or in the hijacking of the server. 687 * 688 * Requires: 689 * 690 * \li 'name' is a valid name. 691 * 692 * \li 'source' is a valid buffer and the first byte of the active 693 * region should be the first byte of a DNS wire format domain name. 694 * 695 * \li 'target' is a valid buffer or 'target' is NULL and 'name' has 696 * a dedicated buffer. 697 * 698 * \li 'dctx' is a valid decompression context. 699 * 700 * Ensures: 701 * 702 * If result is success: 703 * \li If 'target' is not NULL, 'name' is attached to it. 704 * 705 * \li Uppercase letters are downcased in the copy iff 706 * DNS_NAME_DOWNCASE is set in options. 707 * 708 * \li The current location in source is advanced, and the used space 709 * in target is updated. 710 * 711 * Result: 712 * \li Success 713 * \li Bad Form: Label Length 714 * \li Bad Form: Unknown Label Type 715 * \li Bad Form: Name Length 716 * \li Bad Form: Compression type not allowed 717 * \li Bad Form: Bad compression pointer 718 * \li Bad Form: Input too short 719 * \li Resource Limit: Too many compression pointers 720 * \li Resource Limit: Not enough space in buffer 721 */ 722 723 isc_result_t 724 dns_name_towire(const dns_name_t *name, dns_compress_t *cctx, 725 isc_buffer_t *target); 726 /*%< 727 * Convert 'name' into wire format, compressing it as specified by the 728 * compression context 'cctx', and storing the result in 'target'. 729 * 730 * Notes: 731 * \li If the compression context allows global compression, then the 732 * global compression table may be updated. 733 * 734 * Requires: 735 * \li 'name' is a valid name 736 * 737 * \li dns_name_countlabels(name) > 0 738 * 739 * \li dns_name_isabsolute(name) == TRUE 740 * 741 * \li target is a valid buffer. 742 * 743 * \li Any offsets specified in a global compression table are valid 744 * for buffer. 745 * 746 * Ensures: 747 * 748 * If the result is success: 749 * 750 * \li The used space in target is updated. 751 * 752 * Returns: 753 * \li Success 754 * \li Resource Limit: Not enough space in buffer 755 */ 756 757 isc_result_t 758 dns_name_fromtext(dns_name_t *name, isc_buffer_t *source, 759 const dns_name_t *origin, unsigned int options, 760 isc_buffer_t *target); 761 /*%< 762 * Convert the textual representation of a DNS name at source 763 * into uncompressed wire form stored in target. 764 * 765 * Notes: 766 * \li Relative domain names will have 'origin' appended to them 767 * unless 'origin' is NULL, in which case relative domain names 768 * will remain relative. 769 * 770 * \li If DNS_NAME_DOWNCASE is set in 'options', any uppercase letters 771 * in 'source' will be downcased when they are copied into 'target'. 772 * 773 * Requires: 774 * 775 * \li 'name' is a valid name. 776 * 777 * \li 'source' is a valid buffer. 778 * 779 * \li 'target' is a valid buffer or 'target' is NULL and 'name' has 780 * a dedicated buffer. 781 * 782 * Ensures: 783 * 784 * If result is success: 785 * \li If 'target' is not NULL, 'name' is attached to it. 786 * 787 * \li Uppercase letters are downcased in the copy iff 788 * DNS_NAME_DOWNCASE is set in 'options'. 789 * 790 * \li The current location in source is advanced, and the used space 791 * in target is updated. 792 * 793 * Result: 794 *\li #ISC_R_SUCCESS 795 *\li #DNS_R_EMPTYLABEL 796 *\li #DNS_R_LABELTOOLONG 797 *\li #DNS_R_BADESCAPE 798 *\li (#DNS_R_BADBITSTRING: should not be returned) 799 *\li (#DNS_R_BITSTRINGTOOLONG: should not be returned) 800 *\li #DNS_R_BADDOTTEDQUAD 801 *\li #ISC_R_NOSPACE 802 *\li #ISC_R_UNEXPECTEDEND 803 */ 804 805 #define DNS_NAME_OMITFINALDOT 0x01U 806 #define DNS_NAME_MASTERFILE 0x02U /* escape $ and @ */ 807 808 isc_result_t 809 dns_name_toprincipal(dns_name_t *name, isc_buffer_t *target); 810 811 isc_result_t 812 dns_name_totext(dns_name_t *name, isc_boolean_t omit_final_dot, 813 isc_buffer_t *target); 814 815 isc_result_t 816 dns_name_totext2(dns_name_t *name, unsigned int options, isc_buffer_t *target); 817 /*%< 818 * Convert 'name' into text format, storing the result in 'target'. 819 * 820 * Notes: 821 *\li If 'omit_final_dot' is true, then the final '.' in absolute 822 * names other than the root name will be omitted. 823 * 824 *\li If DNS_NAME_OMITFINALDOT is set in options, then the final '.' 825 * in absolute names other than the root name will be omitted. 826 * 827 *\li If DNS_NAME_MASTERFILE is set in options, '$' and '@' will also 828 * be escaped. 829 * 830 *\li If dns_name_countlabels == 0, the name will be "@", representing the 831 * current origin as described by RFC1035. 832 * 833 *\li The name is not NUL terminated. 834 * 835 * Requires: 836 * 837 *\li 'name' is a valid name 838 * 839 *\li 'target' is a valid buffer. 840 * 841 *\li if dns_name_isabsolute == FALSE, then omit_final_dot == FALSE 842 * 843 * Ensures: 844 * 845 *\li If the result is success: 846 * the used space in target is updated. 847 * 848 * Returns: 849 *\li #ISC_R_SUCCESS 850 *\li #ISC_R_NOSPACE 851 */ 852 853 #define DNS_NAME_MAXTEXT 1023 854 /*%< 855 * The maximum length of the text representation of a domain 856 * name as generated by dns_name_totext(). This does not 857 * include space for a terminating NULL. 858 * 859 * This definition is conservative - the actual maximum 860 * is 1004, derived as follows: 861 * 862 * A backslash-decimal escaped character takes 4 bytes. 863 * A wire-encoded name can be up to 255 bytes and each 864 * label is one length byte + at most 63 bytes of data. 865 * Maximizing the label lengths gives us a name of 866 * three 63-octet labels, one 61-octet label, and the 867 * root label: 868 * 869 * 1 + 63 + 1 + 63 + 1 + 63 + 1 + 61 + 1 = 255 870 * 871 * When printed, this is (3 * 63 + 61) * 4 872 * bytes for the escaped label data + 4 bytes for the 873 * dot terminating each label = 1004 bytes total. 874 */ 875 876 isc_result_t 877 dns_name_tofilenametext(dns_name_t *name, isc_boolean_t omit_final_dot, 878 isc_buffer_t *target); 879 /*%< 880 * Convert 'name' into an alternate text format appropriate for filenames, 881 * storing the result in 'target'. The name data is downcased, guaranteeing 882 * that the filename does not depend on the case of the converted name. 883 * 884 * Notes: 885 *\li If 'omit_final_dot' is true, then the final '.' in absolute 886 * names other than the root name will be omitted. 887 * 888 *\li The name is not NUL terminated. 889 * 890 * Requires: 891 * 892 *\li 'name' is a valid absolute name 893 * 894 *\li 'target' is a valid buffer. 895 * 896 * Ensures: 897 * 898 *\li If the result is success: 899 * the used space in target is updated. 900 * 901 * Returns: 902 *\li #ISC_R_SUCCESS 903 *\li #ISC_R_NOSPACE 904 */ 905 906 isc_result_t 907 dns_name_downcase(dns_name_t *source, dns_name_t *name, 908 isc_buffer_t *target); 909 /*%< 910 * Downcase 'source'. 911 * 912 * Requires: 913 * 914 *\li 'source' and 'name' are valid names. 915 * 916 *\li If source == name, then 917 * 'source' must not be read-only 918 * 919 *\li Otherwise, 920 * 'target' is a valid buffer or 'target' is NULL and 921 * 'name' has a dedicated buffer. 922 * 923 * Returns: 924 *\li #ISC_R_SUCCESS 925 *\li #ISC_R_NOSPACE 926 * 927 * Note: if source == name, then the result will always be ISC_R_SUCCESS. 928 */ 929 930 isc_result_t 931 dns_name_concatenate(dns_name_t *prefix, dns_name_t *suffix, 932 dns_name_t *name, isc_buffer_t *target); 933 /*%< 934 * Concatenate 'prefix' and 'suffix'. 935 * 936 * Requires: 937 * 938 *\li 'prefix' is a valid name or NULL. 939 * 940 *\li 'suffix' is a valid name or NULL. 941 * 942 *\li 'name' is a valid name or NULL. 943 * 944 *\li 'target' is a valid buffer or 'target' is NULL and 'name' has 945 * a dedicated buffer. 946 * 947 *\li If 'prefix' is absolute, 'suffix' must be NULL or the empty name. 948 * 949 * Ensures: 950 * 951 *\li On success, 952 * If 'target' is not NULL and 'name' is not NULL, then 'name' 953 * is attached to it. 954 * The used space in target is updated. 955 * 956 * Returns: 957 *\li #ISC_R_SUCCESS 958 *\li #ISC_R_NOSPACE 959 *\li #DNS_R_NAMETOOLONG 960 */ 961 962 void 963 dns_name_split(dns_name_t *name, unsigned int suffixlabels, 964 dns_name_t *prefix, dns_name_t *suffix); 965 /*%< 966 * 967 * Split 'name' into two pieces on a label boundary. 968 * 969 * Notes: 970 * \li 'name' is split such that 'suffix' holds the most significant 971 * 'suffixlabels' labels. All other labels are stored in 'prefix'. 972 * 973 *\li Copying name data is avoided as much as possible, so 'prefix' 974 * and 'suffix' will end up pointing at the data for 'name'. 975 * 976 *\li It is legitimate to pass a 'prefix' or 'suffix' that has 977 * its name data stored someplace other than the dedicated buffer. 978 * This is useful to avoid name copying in the calling function. 979 * 980 *\li It is also legitimate to pass a 'prefix' or 'suffix' that is 981 * the same dns_name_t as 'name'. 982 * 983 * Requires: 984 *\li 'name' is a valid name. 985 * 986 *\li 'suffixlabels' cannot exceed the number of labels in 'name'. 987 * 988 * \li 'prefix' is a valid name or NULL, and cannot be read-only. 989 * 990 *\li 'suffix' is a valid name or NULL, and cannot be read-only. 991 * 992 * Ensures: 993 * 994 *\li On success: 995 * If 'prefix' is not NULL it will contain the least significant 996 * labels. 997 * If 'suffix' is not NULL it will contain the most significant 998 * labels. dns_name_countlabels(suffix) will be equal to 999 * suffixlabels. 1000 * 1001 *\li On failure: 1002 * Either 'prefix' or 'suffix' is invalidated (depending 1003 * on which one the problem was encountered with). 1004 * 1005 * Returns: 1006 *\li #ISC_R_SUCCESS No worries. (This function should always success). 1007 */ 1008 1009 isc_result_t 1010 dns_name_dup(const dns_name_t *source, isc_mem_t *mctx, 1011 dns_name_t *target); 1012 /*%< 1013 * Make 'target' a dynamically allocated copy of 'source'. 1014 * 1015 * Requires: 1016 * 1017 *\li 'source' is a valid non-empty name. 1018 * 1019 *\li 'target' is a valid name that is not read-only. 1020 * 1021 *\li 'mctx' is a valid memory context. 1022 */ 1023 1024 isc_result_t 1025 dns_name_dupwithoffsets(dns_name_t *source, isc_mem_t *mctx, 1026 dns_name_t *target); 1027 /*%< 1028 * Make 'target' a read-only dynamically allocated copy of 'source'. 1029 * 'target' will also have a dynamically allocated offsets table. 1030 * 1031 * Requires: 1032 * 1033 *\li 'source' is a valid non-empty name. 1034 * 1035 *\li 'target' is a valid name that is not read-only. 1036 * 1037 *\li 'target' has no offsets table. 1038 * 1039 *\li 'mctx' is a valid memory context. 1040 */ 1041 1042 void 1043 dns_name_free(dns_name_t *name, isc_mem_t *mctx); 1044 /*%< 1045 * Free 'name'. 1046 * 1047 * Requires: 1048 * 1049 *\li 'name' is a valid name created previously in 'mctx' by dns_name_dup(). 1050 * 1051 *\li 'mctx' is a valid memory context. 1052 * 1053 * Ensures: 1054 * 1055 *\li All dynamic resources used by 'name' are freed and the name is 1056 * invalidated. 1057 */ 1058 1059 isc_result_t 1060 dns_name_digest(dns_name_t *name, dns_digestfunc_t digest, void *arg); 1061 /*%< 1062 * Send 'name' in DNSSEC canonical form to 'digest'. 1063 * 1064 * Requires: 1065 * 1066 *\li 'name' is a valid name. 1067 * 1068 *\li 'digest' is a valid dns_digestfunc_t. 1069 * 1070 * Ensures: 1071 * 1072 *\li If successful, the DNSSEC canonical form of 'name' will have been 1073 * sent to 'digest'. 1074 * 1075 *\li If digest() returns something other than ISC_R_SUCCESS, that result 1076 * will be returned as the result of dns_name_digest(). 1077 * 1078 * Returns: 1079 * 1080 *\li #ISC_R_SUCCESS 1081 * 1082 *\li Many other results are possible if not successful. 1083 * 1084 */ 1085 1086 isc_boolean_t 1087 dns_name_dynamic(dns_name_t *name); 1088 /*%< 1089 * Returns whether there is dynamic memory associated with this name. 1090 * 1091 * Requires: 1092 * 1093 *\li 'name' is a valid name. 1094 * 1095 * Returns: 1096 * 1097 *\li 'ISC_TRUE' if the name is dynamic otherwise 'ISC_FALSE'. 1098 */ 1099 1100 isc_result_t 1101 dns_name_print(dns_name_t *name, FILE *stream); 1102 /*%< 1103 * Print 'name' on 'stream'. 1104 * 1105 * Requires: 1106 * 1107 *\li 'name' is a valid name. 1108 * 1109 *\li 'stream' is a valid stream. 1110 * 1111 * Returns: 1112 * 1113 *\li #ISC_R_SUCCESS 1114 * 1115 *\li Any error that dns_name_totext() can return. 1116 */ 1117 1118 void 1119 dns_name_format(dns_name_t *name, char *cp, unsigned int size); 1120 /*%< 1121 * Format 'name' as text appropriate for use in log messages. 1122 * 1123 * Store the formatted name at 'cp', writing no more than 1124 * 'size' bytes. The resulting string is guaranteed to be 1125 * null terminated. 1126 * 1127 * The formatted name will have a terminating dot only if it is 1128 * the root. 1129 * 1130 * This function cannot fail, instead any errors are indicated 1131 * in the returned text. 1132 * 1133 * Requires: 1134 * 1135 *\li 'name' is a valid name. 1136 * 1137 *\li 'cp' points a valid character array of size 'size'. 1138 * 1139 *\li 'size' > 0. 1140 * 1141 */ 1142 1143 isc_result_t 1144 dns_name_tostring(dns_name_t *source, char **target, isc_mem_t *mctx); 1145 /*%< 1146 * Convert 'name' to string format, allocating sufficient memory to 1147 * hold it (free with isc_mem_free()). 1148 * 1149 * Differs from dns_name_format in that it allocates its own memory. 1150 * 1151 * Requires: 1152 * 1153 *\li 'name' is a valid name. 1154 *\li 'target' is not NULL. 1155 *\li '*target' is NULL. 1156 * 1157 * Returns: 1158 * 1159 *\li ISC_R_SUCCESS 1160 *\li ISC_R_NOMEMORY 1161 * 1162 *\li Any error that dns_name_totext() can return. 1163 */ 1164 1165 isc_result_t 1166 dns_name_fromstring(dns_name_t *target, const char *src, unsigned int options, 1167 isc_mem_t *mctx); 1168 isc_result_t 1169 dns_name_fromstring2(dns_name_t *target, const char *src, 1170 const dns_name_t *origin, unsigned int options, 1171 isc_mem_t *mctx); 1172 /*%< 1173 * Convert a string to a name and place it in target, allocating memory 1174 * as necessary. 'options' has the same semantics as that of 1175 * dns_name_fromtext(). 1176 * 1177 * If 'target' has a buffer then the name will be copied into it rather than 1178 * memory being allocated. 1179 * 1180 * Requires: 1181 * 1182 * \li 'target' is a valid name that is not read-only. 1183 * \li 'src' is not NULL. 1184 * 1185 * Returns: 1186 * 1187 *\li #ISC_R_SUCCESS 1188 * 1189 *\li Any error that dns_name_fromtext() can return. 1190 * 1191 *\li Any error that dns_name_dup() can return. 1192 */ 1193 1194 isc_result_t 1195 dns_name_settotextfilter(dns_name_totextfilter_t proc); 1196 /*%< 1197 * Set / clear a thread specific function 'proc' to be called at the 1198 * end of dns_name_totext(). 1199 * 1200 * Note: Under Windows you need to call "dns_name_settotextfilter(NULL);" 1201 * prior to exiting the thread otherwise memory will be leaked. 1202 * For other platforms, which are pthreads based, this is still a good 1203 * idea but not required. 1204 * 1205 * Returns 1206 *\li #ISC_R_SUCCESS 1207 *\li #ISC_R_UNEXPECTED 1208 */ 1209 1210 #define DNS_NAME_FORMATSIZE (DNS_NAME_MAXTEXT + 1) 1211 /*%< 1212 * Suggested size of buffer passed to dns_name_format(). 1213 * Includes space for the terminating NULL. 1214 */ 1215 1216 isc_result_t 1217 dns_name_copy(dns_name_t *source, dns_name_t *dest, isc_buffer_t *target); 1218 /*%< 1219 * Makes 'dest' refer to a copy of the name in 'source'. The data are 1220 * either copied to 'target' or the dedicated buffer in 'dest'. 1221 * 1222 * Requires: 1223 * \li 'source' is a valid name. 1224 * 1225 * \li 'dest' is an initialized name with a dedicated buffer. 1226 * 1227 * \li 'target' is NULL or an initialized buffer. 1228 * 1229 * \li Either dest has a dedicated buffer or target != NULL. 1230 * 1231 * Ensures: 1232 * 1233 *\li On success, the used space in target is updated. 1234 * 1235 * Returns: 1236 *\li #ISC_R_SUCCESS 1237 *\li #ISC_R_NOSPACE 1238 */ 1239 1240 isc_boolean_t 1241 dns_name_ishostname(const dns_name_t *name, isc_boolean_t wildcard); 1242 /*%< 1243 * Return if 'name' is a valid hostname. RFC 952 / RFC 1123. 1244 * If 'wildcard' is ISC_TRUE then allow the first label of name to 1245 * be a wildcard. 1246 * The root is also accepted. 1247 * 1248 * Requires: 1249 * 'name' to be valid. 1250 */ 1251 1252 1253 isc_boolean_t 1254 dns_name_ismailbox(const dns_name_t *name); 1255 /*%< 1256 * Return if 'name' is a valid mailbox. RFC 821. 1257 * 1258 * Requires: 1259 * \li 'name' to be valid. 1260 */ 1261 1262 isc_boolean_t 1263 dns_name_internalwildcard(const dns_name_t *name); 1264 /*%< 1265 * Return if 'name' contains a internal wildcard name. 1266 * 1267 * Requires: 1268 * \li 'name' to be valid. 1269 */ 1270 1271 void 1272 dns_name_destroy(void); 1273 /*%< 1274 * Cleanup dns_name_settotextfilter() / dns_name_totext() state. 1275 * 1276 * This should be called as part of the final cleanup process. 1277 * 1278 * Note: dns_name_settotextfilter(NULL); should be called for all 1279 * threads which have called dns_name_settotextfilter() with a 1280 * non-NULL argument prior to calling dns_name_destroy(); 1281 */ 1282 1283 isc_boolean_t 1284 dns_name_isdnssd(const dns_name_t *owner); 1285 /*%< 1286 * Determine if the 'owner' is a DNS-SD prefix. 1287 */ 1288 1289 isc_boolean_t 1290 dns_name_isrfc1918(const dns_name_t *owner); 1291 /*%< 1292 * Determine if the 'name' is in the RFC 1918 reverse namespace. 1293 */ 1294 1295 isc_boolean_t 1296 dns_name_isula(const dns_name_t *owner); 1297 /*%< 1298 * Determine if the 'name' is in the ULA reverse namespace. 1299 */ 1300 1301 ISC_LANG_ENDDECLS 1302 1303 /* 1304 *** High Performance Macros 1305 ***/ 1306 1307 /* 1308 * WARNING: Use of these macros by applications may require recompilation 1309 * of the application in some situations where calling the function 1310 * would not. 1311 * 1312 * WARNING: No assertion checking is done for these macros. 1313 */ 1314 1315 #define DNS_NAME_INIT(n, o) \ 1316 do { \ 1317 dns_name_t *_n = (n); \ 1318 /* memset(_n, 0, sizeof(*_n)); */ \ 1319 _n->magic = DNS_NAME_MAGIC; \ 1320 _n->ndata = NULL; \ 1321 _n->length = 0; \ 1322 _n->labels = 0; \ 1323 _n->attributes = 0; \ 1324 _n->offsets = (o); \ 1325 _n->buffer = NULL; \ 1326 ISC_LINK_INIT(_n, link); \ 1327 ISC_LIST_INIT(_n->list); \ 1328 } while (0) 1329 1330 #define DNS_NAME_RESET(n) \ 1331 do { \ 1332 (n)->ndata = NULL; \ 1333 (n)->length = 0; \ 1334 (n)->labels = 0; \ 1335 (n)->attributes &= ~DNS_NAMEATTR_ABSOLUTE; \ 1336 if ((n)->buffer != NULL) \ 1337 isc_buffer_clear((n)->buffer); \ 1338 } while (0) 1339 1340 #define DNS_NAME_SETBUFFER(n, b) \ 1341 (n)->buffer = (b) 1342 1343 #define DNS_NAME_ISABSOLUTE(n) \ 1344 (((n)->attributes & DNS_NAMEATTR_ABSOLUTE) != 0 ? ISC_TRUE : ISC_FALSE) 1345 1346 #define DNS_NAME_COUNTLABELS(n) \ 1347 ((n)->labels) 1348 1349 #define DNS_NAME_TOREGION(n, r) \ 1350 do { \ 1351 (r)->base = (n)->ndata; \ 1352 (r)->length = (n)->length; \ 1353 } while (0) 1354 1355 #define DNS_NAME_SPLIT(n, l, p, s) \ 1356 do { \ 1357 dns_name_t *_n = (n); \ 1358 dns_name_t *_p = (p); \ 1359 dns_name_t *_s = (s); \ 1360 unsigned int _l = (l); \ 1361 if (_p != NULL) \ 1362 dns_name_getlabelsequence(_n, 0, _n->labels - _l, _p); \ 1363 if (_s != NULL) \ 1364 dns_name_getlabelsequence(_n, _n->labels - _l, _l, _s); \ 1365 } while (0) 1366 1367 #ifdef DNS_NAME_USEINLINE 1368 1369 #define dns_name_init(n, o) DNS_NAME_INIT(n, o) 1370 #define dns_name_reset(n) DNS_NAME_RESET(n) 1371 #define dns_name_setbuffer(n, b) DNS_NAME_SETBUFFER(n, b) 1372 #define dns_name_countlabels(n) DNS_NAME_COUNTLABELS(n) 1373 #define dns_name_isabsolute(n) DNS_NAME_ISABSOLUTE(n) 1374 #define dns_name_toregion(n, r) DNS_NAME_TOREGION(n, r) 1375 #define dns_name_split(n, l, p, s) DNS_NAME_SPLIT(n, l, p, s) 1376 1377 #endif /* DNS_NAME_USEINLINE */ 1378 1379 #endif /* DNS_NAME_H */ 1380