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