contrib/bind-9.3/lib/dns/include/dns/name.h

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