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