1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * Permission to use, copy, modify, and/or distribute this software for any 5 * purpose with or without fee is hereby granted, provided that the above 6 * copyright notice and this permission notice appear in all copies. 7 * 8 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 9 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 10 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 11 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 12 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 13 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 14 * PERFORMANCE OF THIS SOFTWARE. 15 */ 16 17 /* $Id: name.h,v 1.13 2022/12/26 19:24:11 jmc Exp $ */ 18 19 #ifndef DNS_NAME_H 20 #define DNS_NAME_H 1 21 22 /***** 23 ***** Module Info 24 *****/ 25 26 /*! \file dns/name.h 27 * \brief 28 * Provides facilities for manipulating DNS names and labels, including 29 * conversions to and from wire format and text format. 30 * 31 * Given the large number of names possible in a nameserver, and because 32 * names occur in rdata, it was important to come up with a very efficient 33 * way of storing name data, but at the same time allow names to be 34 * manipulated. The decision was to store names in uncompressed wire format, 35 * and not to make them fully abstracted objects; i.e. certain parts of the 36 * server know names are stored that way. This saves a lot of memory, and 37 * makes adding names to messages easy. Having much of the server know 38 * the representation would be perilous, and we certainly don't want each 39 * user of names to be manipulating such a low-level structure. This is 40 * where the Names and Labels module comes in. The module allows name or 41 * label handles to be created and attached to uncompressed wire format 42 * regions. All name operations and conversions are done through these 43 * handles. 44 * 45 * MP: 46 *\li Clients of this module must impose any required synchronization. 47 * 48 * Reliability: 49 *\li This module deals with low-level byte streams. Errors in any of 50 * the functions are likely to crash the server or corrupt memory. 51 * 52 * Resources: 53 *\li None. 54 * 55 * Security: 56 * 57 *\li *** WARNING *** 58 * 59 *\li dns_name_fromwire() deals with raw network data. An error in 60 * this routine could result in the failure or hijacking of the server. 61 * 62 * Standards: 63 *\li RFC1035 64 *\li Draft EDNS0 (0) 65 *\li Draft Binary Labels (2) 66 * 67 */ 68 69 /*** 70 *** Imports 71 ***/ 72 73 #include <stdio.h> 74 75 #include <isc/region.h> /* Required for storage size of dns_label_t. */ 76 77 #include <dns/types.h> 78 79 /***** 80 ***** Labels 81 ***** 82 ***** A 'label' is basically a region. It contains one DNS wire format 83 ***** label of type 00 (ordinary). 84 *****/ 85 86 /***** 87 ***** Names 88 ***** 89 ***** A 'name' is a handle to a binary region. It contains a sequence of one 90 ***** or more DNS wire format labels of type 00 (ordinary). 91 ***** Note that all names are not required to end with the root label, 92 ***** as they are in the actual DNS wire protocol. 93 *****/ 94 95 /*** 96 *** Types 97 ***/ 98 99 /*% 100 * Clients are strongly discouraged from using this type directly, with 101 * the exception of the 'link' and 'list' fields which may be used directly 102 * for whatever purpose the client desires. 103 */ 104 struct dns_name { 105 unsigned char * ndata; 106 unsigned int length; 107 unsigned int labels; 108 unsigned int attributes; 109 unsigned char * offsets; 110 isc_buffer_t * buffer; 111 ISC_LINK(dns_name_t) link; 112 ISC_LIST(dns_rdataset_t) list; 113 }; 114 115 #define DNS_NAMEATTR_ABSOLUTE 0x00000001 116 #define DNS_NAMEATTR_READONLY 0x00000002 117 #define DNS_NAMEATTR_DYNAMIC 0x00000004 118 #define DNS_NAMEATTR_DYNOFFSETS 0x00000008 119 #define DNS_NAMEATTR_NOCOMPRESS 0x00000010 120 /* 121 * Attributes below 0x0100 reserved for name.c usage. 122 */ 123 #define DNS_NAMEATTR_CACHE 0x00000100 /*%< Used by resolver. */ 124 #define DNS_NAMEATTR_ANSWER 0x00000200 /*%< Used by resolver. */ 125 #define DNS_NAMEATTR_NCACHE 0x00000400 /*%< Used by resolver. */ 126 #define DNS_NAMEATTR_CHAINING 0x00000800 /*%< Used by resolver. */ 127 #define DNS_NAMEATTR_CHASE 0x00001000 /*%< Used by resolver. */ 128 #define DNS_NAMEATTR_WILDCARD 0x00002000 /*%< Used by server. */ 129 #define DNS_NAMEATTR_PREREQUISITE 0x00004000 /*%< Used by client. */ 130 #define DNS_NAMEATTR_UPDATE 0x00008000 /*%< Used by client. */ 131 #define DNS_NAMEATTR_HASUPDATEREC 0x00010000 /*%< Used by client. */ 132 133 /* 134 * Various flags. 135 */ 136 #define DNS_NAME_DOWNCASE 0x0001 137 #define DNS_NAME_CHECKNAMES 0x0002 /*%< Used by rdata. */ 138 #define DNS_NAME_CHECKNAMESFAIL 0x0004 /*%< Used by rdata. */ 139 #define DNS_NAME_CHECKREVERSE 0x0008 /*%< Used by rdata. */ 140 #define DNS_NAME_CHECKMX 0x0010 /*%< Used by rdata. */ 141 #define DNS_NAME_CHECKMXFAIL 0x0020 /*%< Used by rdata. */ 142 143 extern dns_name_t *dns_rootname; 144 145 /*% 146 * Standard size of a wire format name 147 */ 148 #define DNS_NAME_MAXWIRE 255 149 150 /*** 151 *** Initialization 152 ***/ 153 154 void 155 dns_name_init(dns_name_t *name, unsigned char *offsets); 156 /*%< 157 * Initialize 'name'. 158 * 159 * Notes: 160 * \li 'offsets' is never required to be non-NULL, but specifying a 161 * dns_offsets_t for 'offsets' will improve the performance of most 162 * name operations if the name is used more than once. 163 * 164 * Requires: 165 * \li 'name' is not NULL and points to a struct dns_name. 166 * 167 * \li offsets == NULL or offsets is a dns_offsets_t. 168 * 169 * Ensures: 170 * \li 'name' is a valid name. 171 * \li dns_name_countlabels(name) == 0 172 * \li dns_name_isabsolute(name) == 0 173 */ 174 175 void 176 dns_name_reset(dns_name_t *name); 177 /*%< 178 * Reinitialize 'name'. 179 * 180 * Notes: 181 * \li This function distinguishes itself from dns_name_init() in two 182 * key ways: 183 * 184 * \li + If any buffer is associated with 'name' (via dns_name_setbuffer() 185 * or by being part of a dns_fixedname_t) the link to the buffer 186 * is retained but the buffer itself is cleared. 187 * 188 * \li + Of the attributes associated with 'name', all are retained except 189 * DNS_NAMEATTR_ABSOLUTE. 190 * 191 * Requires: 192 * \li 'name' is a valid name. 193 * 194 * Ensures: 195 * \li 'name' is a valid name. 196 * \li dns_name_countlabels(name) == 0 197 * \li dns_name_isabsolute(name) == 0 198 */ 199 200 void 201 dns_name_invalidate(dns_name_t *name); 202 /*%< 203 * Make 'name' invalid. 204 * 205 * Requires: 206 * \li 'name' is a valid name. 207 * 208 * Ensures: 209 * \li If assertion checking is enabled, future attempts to use 'name' 210 * without initializing it will cause an assertion failure. 211 * 212 * \li If the name had a dedicated buffer, that association is ended. 213 */ 214 215 /*** 216 *** Dedicated Buffers 217 ***/ 218 219 void 220 dns_name_setbuffer(dns_name_t *name, isc_buffer_t *buffer); 221 /*%< 222 * Dedicate a buffer for use with 'name'. 223 * 224 * Notes: 225 * \li Specification of a target buffer in dns_name_fromwire(), 226 * dns_name_fromtext(), and dns_name_concatenate() is optional if 227 * 'name' has a dedicated buffer. 228 * 229 * \li The caller must not write to buffer until the name has been 230 * invalidated or is otherwise known not to be in use. 231 * 232 * \li If buffer is NULL and the name previously had a dedicated buffer, 233 * than that buffer is no longer dedicated to use with this name. 234 * The caller is responsible for ensuring that the storage used by 235 * the name remains valid. 236 * 237 * Requires: 238 * \li 'name' is a valid name. 239 * 240 * \li 'buffer' is a valid binary buffer and 'name' doesn't have a 241 * dedicated buffer already, or 'buffer' is NULL. 242 */ 243 244 /*** 245 *** Properties 246 ***/ 247 248 int 249 dns_name_isabsolute(const dns_name_t *name); 250 /*%< 251 * Does 'name' end in the root label? 252 * 253 * Requires: 254 * \li 'name' is a valid name 255 * 256 * Returns: 257 * \li TRUE The last label in 'name' is the root label. 258 * \li FALSE The last label in 'name' is not the root label. 259 */ 260 261 unsigned int 262 dns_name_hash(dns_name_t *name, int case_sensitive); 263 /*%< 264 * Provide a hash value for 'name'. 265 * 266 * Note: if 'case_sensitive' is 0, then names which differ only in 267 * case will have the same hash value. 268 * 269 * Requires: 270 * \li 'name' is a valid name 271 * 272 * Returns: 273 * \li A hash value 274 */ 275 276 /* 277 *** Comparisons 278 ***/ 279 280 dns_namereln_t 281 dns_name_fullcompare(const dns_name_t *name1, const dns_name_t *name2, 282 int *orderp, unsigned int *nlabelsp); 283 /*%< 284 * Determine the relative ordering under the DNSSEC order relation of 285 * 'name1' and 'name2', and also determine the hierarchical 286 * relationship of the names. 287 * 288 * Note: It makes no sense for one of the names to be relative and the 289 * other absolute. If both names are relative, then to be meaningfully 290 * compared the caller must ensure that they are both relative to the 291 * same domain. 292 * 293 * Requires: 294 *\li 'name1' is a valid name 295 * 296 *\li dns_name_countlabels(name1) > 0 297 * 298 *\li 'name2' is a valid name 299 * 300 *\li dns_name_countlabels(name2) > 0 301 * 302 *\li orderp and nlabelsp are valid pointers. 303 * 304 *\li Either name1 is absolute and name2 is absolute, or neither is. 305 * 306 * Ensures: 307 * 308 *\li *orderp is < 0 if name1 < name2, 0 if name1 = name2, > 0 if 309 * name1 > name2. 310 * 311 *\li *nlabelsp is the number of common significant labels. 312 * 313 * Returns: 314 *\li dns_namereln_none There's no hierarchical relationship 315 * between name1 and name2. 316 *\li dns_namereln_contains name1 properly contains name2; i.e. 317 * name2 is a proper subdomain of name1. 318 *\li dns_namereln_subdomain name1 is a proper subdomain of name2. 319 *\li dns_namereln_equal name1 and name2 are equal. 320 *\li dns_namereln_commonancestor name1 and name2 share a common 321 * ancestor. 322 */ 323 324 int 325 dns_name_compare(const dns_name_t *name1, const dns_name_t *name2); 326 /*%< 327 * Determine the relative ordering under the DNSSEC order relation of 328 * 'name1' and 'name2'. 329 * 330 * Note: It makes no sense for one of the names to be relative and the 331 * other absolute. If both names are relative, then to be meaningfully 332 * compared the caller must ensure that they are both relative to the 333 * same domain. 334 * 335 * Requires: 336 * \li 'name1' is a valid name 337 * 338 * \li 'name2' is a valid name 339 * 340 * \li Either name1 is absolute and name2 is absolute, or neither is. 341 * 342 * Returns: 343 * \li < 0 'name1' is less than 'name2' 344 * \li 0 'name1' is equal to 'name2' 345 * \li > 0 'name1' is greater than 'name2' 346 */ 347 348 int 349 dns_name_equal(const dns_name_t *name1, const dns_name_t *name2); 350 /*%< 351 * Are 'name1' and 'name2' equal? 352 * 353 * Notes: 354 * \li Because it only needs to test for equality, dns_name_equal() can be 355 * significantly faster than dns_name_fullcompare() or dns_name_compare(). 356 * 357 * \li Offset tables are not used in the comparison. 358 * 359 * \li It makes no sense for one of the names to be relative and the 360 * other absolute. If both names are relative, then to be meaningfully 361 * compared the caller must ensure that they are both relative to the 362 * same domain. 363 * 364 * Requires: 365 * \li 'name1' is a valid name 366 * 367 * \li 'name2' is a valid name 368 * 369 * \li Either name1 is absolute and name2 is absolute, or neither is. 370 * 371 * Returns: 372 * \li 1 'name1' and 'name2' are equal 373 * \li 0 'name1' and 'name2' are not equal 374 */ 375 376 int 377 dns_name_caseequal(const dns_name_t *name1, const dns_name_t *name2); 378 /*%< 379 * Case sensitive version of dns_name_equal(). 380 */ 381 382 int 383 dns_name_issubdomain(const dns_name_t *name1, const dns_name_t *name2); 384 /*%< 385 * Is 'name1' a subdomain of 'name2'? 386 * 387 * Notes: 388 * \li name1 is a subdomain of name2 if name1 is contained in name2, or 389 * name1 equals name2. 390 * 391 * \li It makes no sense for one of the names to be relative and the 392 * other absolute. If both names are relative, then to be meaningfully 393 * compared the caller must ensure that they are both relative to the 394 * same domain. 395 * 396 * Requires: 397 * \li 'name1' is a valid name 398 * 399 * \li 'name2' is a valid name 400 * 401 * \li Either name1 is absolute and name2 is absolute, or neither is. 402 * 403 * Returns: 404 * \li TRUE 'name1' is a subdomain of 'name2' 405 * \li FALSE 'name1' is not a subdomain of 'name2' 406 */ 407 408 /*** 409 *** Labels 410 ***/ 411 412 unsigned int 413 dns_name_countlabels(const dns_name_t *name); 414 /*%< 415 * How many labels does 'name' have? 416 * 417 * Notes: 418 * \li In this case, as in other places, a 'label' is an ordinary label. 419 * 420 * Requires: 421 * \li 'name' is a valid name 422 * 423 * Ensures: 424 * \li The result is <= 128. 425 * 426 * Returns: 427 * \li The number of labels in 'name'. 428 */ 429 430 void 431 dns_name_getlabel(const dns_name_t *name, unsigned int n, dns_label_t *label); 432 /*%< 433 * Make 'label' refer to the 'n'th least significant label of 'name'. 434 * 435 * Notes: 436 * \li Numbering starts at 0. 437 * 438 * \li Given "rc.vix.com.", the label 0 is "rc", and label 3 is the 439 * root label. 440 * 441 * \li 'label' refers to the same memory as 'name', so 'name' must not 442 * be changed while 'label' is still in use. 443 * 444 * Requires: 445 * \li n < dns_name_countlabels(name) 446 */ 447 448 void 449 dns_name_getlabelsequence(const dns_name_t *source, unsigned int first, 450 unsigned int n, dns_name_t *target); 451 /*%< 452 * Make 'target' refer to the 'n' labels including and following 'first' 453 * in 'source'. 454 * 455 * Notes: 456 * \li Numbering starts at 0. 457 * 458 * \li Given "rc.vix.com.", the label 0 is "rc", and label 3 is the 459 * root label. 460 * 461 * \li 'target' refers to the same memory as 'source', so 'source' 462 * must not be changed while 'target' is still in use. 463 * 464 * Requires: 465 * \li 'source' and 'target' are valid names. 466 * 467 * \li first < dns_name_countlabels(name) 468 * 469 * \li first + n <= dns_name_countlabels(name) 470 */ 471 472 void 473 dns_name_clone(const dns_name_t *source, dns_name_t *target); 474 /*%< 475 * Make 'target' refer to the same name as 'source'. 476 * 477 * Notes: 478 * 479 * \li 'target' refers to the same memory as 'source', so 'source' 480 * must not be changed while 'target' is still in use. 481 * 482 * \li This call is functionally equivalent to: 483 * 484 * \code 485 * dns_name_getlabelsequence(source, 0, 486 * dns_name_countlabels(source), 487 * target); 488 * \endcode 489 * 490 * but is more efficient. Also, dns_name_clone() works even if 'source' 491 * is empty. 492 * 493 * Requires: 494 * 495 * \li 'source' is a valid name. 496 * 497 * \li 'target' is a valid name that is not read-only. 498 */ 499 500 /*** 501 *** Conversions 502 ***/ 503 504 void 505 dns_name_fromregion(dns_name_t *name, const isc_region_t *r); 506 /*%< 507 * Make 'name' refer to region 'r'. 508 * 509 * Note: 510 * \li If the conversion encounters a root label before the end of the 511 * region the conversion stops and the length is set to the length 512 * so far converted. A maximum of 255 bytes is converted. 513 * 514 * Requires: 515 * \li The data in 'r' is a sequence of one or more type 00 or type 01000001 516 * labels. 517 */ 518 519 void 520 dns_name_toregion(dns_name_t *name, isc_region_t *r); 521 /*%< 522 * Make 'r' refer to 'name'. 523 * 524 * Requires: 525 * 526 * \li 'name' is a valid name. 527 * 528 * \li 'r' is a valid region. 529 */ 530 531 isc_result_t 532 dns_name_fromwire(dns_name_t *name, isc_buffer_t *source, 533 dns_decompress_t *dctx, unsigned int options, 534 isc_buffer_t *target); 535 /*%< 536 * Copy the possibly-compressed name at source (active region) into target, 537 * decompressing it. 538 * 539 * Notes: 540 * \li Decompression policy is controlled by 'dctx'. 541 * 542 * \li If DNS_NAME_DOWNCASE is set, any uppercase letters in 'source' will be 543 * downcased when they are copied into 'target'. 544 * 545 * Security: 546 * 547 * \li *** WARNING *** 548 * 549 * \li This routine will often be used when 'source' contains raw network 550 * data. A programming error in this routine could result in a denial 551 * of service, or in the hijacking of the server. 552 * 553 * Requires: 554 * 555 * \li 'name' is a valid name. 556 * 557 * \li 'source' is a valid buffer and the first byte of the active 558 * region should be the first byte of a DNS wire format domain name. 559 * 560 * \li 'target' is a valid buffer or 'target' is NULL and 'name' has 561 * a dedicated buffer. 562 * 563 * \li 'dctx' is a valid decompression context. 564 * 565 * Ensures: 566 * 567 * If result is success: 568 * \li If 'target' is not NULL, 'name' is attached to it. 569 * 570 * \li Uppercase letters are downcased in the copy iff 571 * DNS_NAME_DOWNCASE is set in options. 572 * 573 * \li The current location in source is advanced, and the used space 574 * in target is updated. 575 * 576 * Result: 577 * \li Success 578 * \li Bad Form: Label Length 579 * \li Bad Form: Unknown Label Type 580 * \li Bad Form: Name Length 581 * \li Bad Form: Compression type not allowed 582 * \li Bad Form: Bad compression pointer 583 * \li Bad Form: Input too short 584 * \li Resource Limit: Too many compression pointers 585 * \li Resource Limit: Not enough space in buffer 586 */ 587 588 isc_result_t 589 dns_name_towire(const dns_name_t *name, dns_compress_t *cctx, 590 isc_buffer_t *target); 591 /*%< 592 * Convert 'name' into wire format, compressing it as specified by the 593 * compression context 'cctx', and storing the result in 'target'. 594 * 595 * Notes: 596 * \li If the compression context allows global compression, then the 597 * global compression table may be updated. 598 * 599 * Requires: 600 * \li 'name' is a valid name 601 * 602 * \li dns_name_countlabels(name) > 0 603 * 604 * \li dns_name_isabsolute(name) == TRUE 605 * 606 * \li target is a valid buffer. 607 * 608 * \li Any offsets specified in a global compression table are valid 609 * for buffer. 610 * 611 * Ensures: 612 * 613 * If the result is success: 614 * 615 * \li The used space in target is updated. 616 * 617 * Returns: 618 * \li Success 619 * \li Resource Limit: Not enough space in buffer 620 */ 621 622 isc_result_t 623 dns_name_fromtext(dns_name_t *name, isc_buffer_t *source, 624 const dns_name_t *origin, unsigned int options, 625 isc_buffer_t *target); 626 /*%< 627 * Convert the textual representation of a DNS name at source 628 * into uncompressed wire form stored in target. 629 * 630 * Notes: 631 * \li Relative domain names will have 'origin' appended to them 632 * unless 'origin' is NULL, in which case relative domain names 633 * will remain relative. 634 * 635 * \li If DNS_NAME_DOWNCASE is set in 'options', any uppercase letters 636 * in 'source' will be downcased when they are copied into 'target'. 637 * 638 * Requires: 639 * 640 * \li 'name' is a valid name. 641 * 642 * \li 'source' is a valid buffer. 643 * 644 * \li 'target' is a valid buffer or 'target' is NULL and 'name' has 645 * a dedicated buffer. 646 * 647 * Ensures: 648 * 649 * If result is success: 650 * \li If 'target' is not NULL, 'name' is attached to it. 651 * 652 * \li Uppercase letters are downcased in the copy iff 653 * DNS_NAME_DOWNCASE is set in 'options'. 654 * 655 * \li The current location in source is advanced, and the used space 656 * in target is updated. 657 * 658 * Result: 659 *\li #ISC_R_SUCCESS 660 *\li #DNS_R_EMPTYLABEL 661 *\li #DNS_R_LABELTOOLONG 662 *\li #DNS_R_BADESCAPE 663 *\li #DNS_R_BADDOTTEDQUAD 664 *\li #ISC_R_NOSPACE 665 *\li #ISC_R_UNEXPECTEDEND 666 */ 667 668 #define DNS_NAME_OMITFINALDOT 0x01U 669 #define DNS_NAME_MASTERFILE 0x02U /* escape $ and @ */ 670 671 isc_result_t 672 dns_name_totext(dns_name_t *name, int omit_final_dot, 673 isc_buffer_t *target); 674 675 isc_result_t 676 dns_name_totext2(dns_name_t *name, unsigned int options, isc_buffer_t *target); 677 /*%< 678 * Convert 'name' into text format, storing the result in 'target'. 679 * 680 * Notes: 681 *\li If 'omit_final_dot' is true, then the final '.' in absolute 682 * names other than the root name will be omitted. 683 * 684 *\li If DNS_NAME_OMITFINALDOT is set in options, then the final '.' 685 * in absolute names other than the root name will be omitted. 686 * 687 *\li If DNS_NAME_MASTERFILE is set in options, '$' and '@' will also 688 * be escaped. 689 * 690 *\li If dns_name_countlabels == 0, the name will be "@", representing the 691 * current origin as described by RFC1035. 692 * 693 *\li The name is not NUL terminated. 694 * 695 * Requires: 696 * 697 *\li 'name' is a valid name 698 * 699 *\li 'target' is a valid buffer. 700 * 701 *\li if dns_name_isabsolute == FALSE, then omit_final_dot == FALSE 702 * 703 * Ensures: 704 * 705 *\li If the result is success: 706 * the used space in target is updated. 707 * 708 * Returns: 709 *\li #ISC_R_SUCCESS 710 *\li #ISC_R_NOSPACE 711 */ 712 713 #define DNS_NAME_MAXTEXT 1023 714 /*%< 715 * The maximum length of the text representation of a domain 716 * name as generated by dns_name_totext(). This does not 717 * include space for a terminating NULL. 718 * 719 * This definition is conservative - the actual maximum 720 * is 1004, derived as follows: 721 * 722 * A backslash-decimal escaped character takes 4 bytes. 723 * A wire-encoded name can be up to 255 bytes and each 724 * label is one length byte + at most 63 bytes of data. 725 * Maximizing the label lengths gives us a name of 726 * three 63-octet labels, one 61-octet label, and the 727 * root label: 728 * 729 * 1 + 63 + 1 + 63 + 1 + 63 + 1 + 61 + 1 = 255 730 * 731 * When printed, this is (3 * 63 + 61) * 4 732 * bytes for the escaped label data + 4 bytes for the 733 * dot terminating each label = 1004 bytes total. 734 */ 735 736 isc_result_t 737 dns_name_downcase(dns_name_t *source, dns_name_t *name, 738 isc_buffer_t *target); 739 /*%< 740 * Downcase 'source'. 741 * 742 * Requires: 743 * 744 *\li 'source' and 'name' are valid names. 745 * 746 *\li If source == name, then 747 * 'source' must not be read-only 748 * 749 *\li Otherwise, 750 * 'target' is a valid buffer or 'target' is NULL and 751 * 'name' has a dedicated buffer. 752 * 753 * Returns: 754 *\li #ISC_R_SUCCESS 755 *\li #ISC_R_NOSPACE 756 * 757 * Note: if source == name, then the result will always be ISC_R_SUCCESS. 758 */ 759 760 isc_result_t 761 dns_name_concatenate(dns_name_t *prefix, dns_name_t *suffix, 762 dns_name_t *name, isc_buffer_t *target); 763 /*%< 764 * Concatenate 'prefix' and 'suffix'. 765 * 766 * Requires: 767 * 768 *\li 'prefix' is a valid name or NULL. 769 * 770 *\li 'suffix' is a valid name or NULL. 771 * 772 *\li 'name' is a valid name or NULL. 773 * 774 *\li 'target' is a valid buffer or 'target' is NULL and 'name' has 775 * a dedicated buffer. 776 * 777 *\li If 'prefix' is absolute, 'suffix' must be NULL or the empty name. 778 * 779 * Ensures: 780 * 781 *\li On success, 782 * If 'target' is not NULL and 'name' is not NULL, then 'name' 783 * is attached to it. 784 * The used space in target is updated. 785 * 786 * Returns: 787 *\li #ISC_R_SUCCESS 788 *\li #ISC_R_NOSPACE 789 *\li #DNS_R_NAMETOOLONG 790 */ 791 792 isc_result_t 793 dns_name_dup(const dns_name_t *source, 794 dns_name_t *target); 795 /*%< 796 * Make 'target' a dynamically allocated copy of 'source'. 797 * 798 * Requires: 799 * 800 *\li 'source' is a valid non-empty name. 801 * 802 *\li 'target' is a valid name that is not read-only. 803 * 804 *\li 'mctx' is a valid memory context. 805 */ 806 807 isc_result_t 808 dns_name_dupwithoffsets(dns_name_t *source, 809 dns_name_t *target); 810 /*%< 811 * Make 'target' a read-only dynamically allocated copy of 'source'. 812 * 'target' will also have a dynamically allocated offsets table. 813 * 814 * Requires: 815 * 816 *\li 'source' is a valid non-empty name. 817 * 818 *\li 'target' is a valid name that is not read-only. 819 * 820 *\li 'target' has no offsets table. 821 * 822 *\li 'mctx' is a valid memory context. 823 */ 824 825 void 826 dns_name_free(dns_name_t *name); 827 /*%< 828 * Free 'name'. 829 * 830 * Requires: 831 * 832 *\li 'name' is a valid name created previously in 'mctx' by dns_name_dup(). 833 * 834 *\li 'mctx' is a valid memory context. 835 * 836 * Ensures: 837 * 838 *\li All dynamic resources used by 'name' are freed and the name is 839 * invalidated. 840 */ 841 842 int 843 dns_name_dynamic(dns_name_t *name); 844 /*%< 845 * Returns whether there is dynamic memory associated with this name. 846 * 847 * Requires: 848 * 849 *\li 'name' is a valid name. 850 * 851 * Returns: 852 * 853 *\li '1' if the name is dynamic otherwise '0'. 854 */ 855 856 void 857 dns_name_format(dns_name_t *name, char *cp, unsigned int size); 858 /*%< 859 * Format 'name' as text appropriate for use in log messages. 860 * 861 * Store the formatted name at 'cp', writing no more than 862 * 'size' bytes. The resulting string is guaranteed to be 863 * null terminated. 864 * 865 * The formatted name will have a terminating dot only if it is 866 * the root. 867 * 868 * This function cannot fail, instead any errors are indicated 869 * in the returned text. 870 * 871 * Requires: 872 * 873 *\li 'name' is a valid name. 874 * 875 *\li 'cp' points a valid character array of size 'size'. 876 * 877 *\li 'size' > 0. 878 * 879 */ 880 881 isc_result_t 882 dns_name_fromstring2(dns_name_t *target, const char *src, 883 const dns_name_t *origin, unsigned int options); 884 /*%< 885 * Convert a string to a name and place it in target, allocating memory 886 * as necessary. 'options' has the same semantics as that of 887 * dns_name_fromtext(). 888 * 889 * If 'target' has a buffer then the name will be copied into it rather than 890 * memory being allocated. 891 * 892 * Requires: 893 * 894 * \li 'target' is a valid name that is not read-only. 895 * \li 'src' is not NULL. 896 * 897 * Returns: 898 * 899 *\li #ISC_R_SUCCESS 900 * 901 *\li Any error that dns_name_fromtext() can return. 902 * 903 *\li Any error that dns_name_dup() can return. 904 */ 905 906 #define DNS_NAME_FORMATSIZE (DNS_NAME_MAXTEXT + 1) 907 /*%< 908 * Suggested size of buffer passed to dns_name_format(). 909 * Includes space for the terminating NULL. 910 */ 911 912 isc_result_t 913 dns_name_copy(dns_name_t *source, dns_name_t *dest, isc_buffer_t *target); 914 /*%< 915 * Makes 'dest' refer to a copy of the name in 'source'. The data are 916 * either copied to 'target' or the dedicated buffer in 'dest'. 917 * 918 * Requires: 919 * \li 'source' is a valid name. 920 * 921 * \li 'dest' is an initialized name with a dedicated buffer. 922 * 923 * \li 'target' is NULL or an initialized buffer. 924 * 925 * \li Either dest has a dedicated buffer or target != NULL. 926 * 927 * Ensures: 928 * 929 *\li On success, the used space in target is updated. 930 * 931 * Returns: 932 *\li #ISC_R_SUCCESS 933 *\li #ISC_R_NOSPACE 934 */ 935 936 #define DNS_NAME_INITABSOLUTE(A,B) { \ 937 A, sizeof(A), sizeof(B), \ 938 DNS_NAMEATTR_READONLY | DNS_NAMEATTR_ABSOLUTE, \ 939 B, NULL, { (void *)-1, (void *)-1}, \ 940 {NULL, NULL} \ 941 } 942 943 #endif /* DNS_NAME_H */ 944