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