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