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