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

   1 /*
   2  * Copyright (C) 2004  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.12 2004/09/08 00:29:34 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(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(dns_name_t *name, dns_compress_t *cctx, isc_buffer_t *target);
 707 /*
 708  * Convert 'name' into wire format, compressing it as specified by the
 709  * compression context 'cctx', and storing the result in 'target'.
 710  *
 711  * Notes:
 712  *      If the compression context allows global compression, then the
 713  *      global compression table may be updated.
 714  *
 715  * Requires:
 716  *      'name' is a valid name
 717  *
 718  *      dns_name_countlabels(name) > 0
 719  *
 720  *      dns_name_isabsolute(name) == TRUE
 721  *
 722  *      target is a valid buffer.
 723  *
 724  *      Any offsets specified in a global compression table are valid
 725  *      for buffer.
 726  *
 727  * Ensures:
 728  *
 729  *      If the result is success:
 730  *
 731  *              The used space in target is updated.
 732  *
 733  * Returns:
 734  *      Success
 735  *      Resource Limit: Not enough space in buffer
 736  */
 737
 738 isc_result_t
 739 dns_name_fromtext(dns_name_t *name, isc_buffer_t *source,
 740                   dns_name_t *origin, unsigned int options,
 741                   isc_buffer_t *target);
 742 /*
 743  * Convert the textual representation of a DNS name at source
 744  * into uncompressed wire form stored in target.
 745  *
 746  * Notes:
 747  *      Relative domain names will have 'origin' appended to them
 748  *      unless 'origin' is NULL, in which case relative domain names
 749  *      will remain relative.
 750  *
 751  *      If DNS_NAME_DOWNCASE is set in 'options', any uppercase letters
 752  *      in 'source' will be downcased when they are copied into 'target'.
 753  *
 754  * Requires:
 755  *
 756  *      'name' is a valid name.
 757  *
 758  *      'source' is a valid buffer.
 759  *
 760  *      'target' is a valid buffer or 'target' is NULL and 'name' has
 761  *      a dedicated buffer.
 762  *
 763  * Ensures:
 764  *
 765  *      If result is success:
 766  *              If 'target' is not NULL, 'name' is attached to it.
 767  *
 768  *              Uppercase letters are downcased in the copy iff
 769  *              DNS_NAME_DOWNCASE is set in 'options'.
 770  *
 771  *              The current location in source is advanced, and the used space
 772  *              in target is updated.
 773  *
 774  * Result:
 775  *      ISC_R_SUCCESS
 776  *      DNS_R_EMPTYLABEL
 777  *      DNS_R_LABELTOOLONG
 778  *      DNS_R_BADESCAPE
 779  *      (DNS_R_BADBITSTRING: should not be returned)
 780  *      (DNS_R_BITSTRINGTOOLONG: should not be returned)
 781  *      DNS_R_BADDOTTEDQUAD
 782  *      ISC_R_NOSPACE
 783  *      ISC_R_UNEXPECTEDEND
 784  */
 785
 786 isc_result_t
 787 dns_name_totext(dns_name_t *name, isc_boolean_t omit_final_dot,
 788                 isc_buffer_t *target);
 789 /*
 790  * Convert 'name' into text format, storing the result in 'target'.
 791  *
 792  * Notes:
 793  *      If 'omit_final_dot' is true, then the final '.' in absolute
 794  *      names other than the root name will be omitted.
 795  *
 796  *      If dns_name_countlabels == 0, the name will be "@", representing the
 797  *      current origin as described by RFC 1035.
 798  *
 799  *      The name is not NUL terminated.
 800  *
 801  * Requires:
 802  *
 803  *      'name' is a valid name
 804  *
 805  *      'target' is a valid buffer.
 806  *
 807  *      if dns_name_isabsolute == FALSE, then omit_final_dot == FALSE
 808  *
 809  * Ensures:
 810  *
 811  *      If the result is success:
 812  *
 813  *              The used space in target is updated.
 814  *
 815  * Returns:
 816  *      ISC_R_SUCCESS
 817  *      ISC_R_NOSPACE
 818  */
 819
 820 #define DNS_NAME_MAXTEXT 1023
 821 /*
 822  * The maximum length of the text representation of a domain
 823  * name as generated by dns_name_totext().  This does not
 824  * include space for a terminating NULL.
 825  *
 826  * This definition is conservative - the actual maximum
 827  * is 1004, derived as follows:
 828  *
 829  *   A backslash-decimal escaped character takes 4 bytes.
 830  *   A wire-encoded name can be up to 255 bytes and each
 831  *   label is one length byte + at most 63 bytes of data.
 832  *   Maximizing the label lengths gives us a name of
 833  *   three 63-octet labels, one 61-octet label, and the
 834  *   root label:
 835  *
 836  *      1 + 63 + 1 + 63 + 1 + 63 + 1 + 61 + 1 = 255
 837  *
 838  *   When printed, this is (3 * 63 + 61) * 4
 839  *   bytes for the escaped label data + 4 bytes for the
 840  *   dot terminating each label = 1004 bytes total.
 841  */
 842
 843 isc_result_t
 844 dns_name_tofilenametext(dns_name_t *name, isc_boolean_t omit_final_dot,
 845                         isc_buffer_t *target);
 846 /*
 847  * Convert 'name' into an alternate text format appropriate for filenames,
 848  * storing the result in 'target'.  The name data is downcased, guaranteeing
 849  * that the filename does not depend on the case of the converted name.
 850  *
 851  * Notes:
 852  *      If 'omit_final_dot' is true, then the final '.' in absolute
 853  *      names other than the root name will be omitted.
 854  *
 855  *      The name is not NUL terminated.
 856  *
 857  * Requires:
 858  *
 859  *      'name' is a valid absolute name
 860  *
 861  *      'target' is a valid buffer.
 862  *
 863  * Ensures:
 864  *
 865  *      If the result is success:
 866  *
 867  *              The used space in target is updated.
 868  *
 869  * Returns:
 870  *      ISC_R_SUCCESS
 871  *      ISC_R_NOSPACE
 872  */
 873
 874 isc_result_t
 875 dns_name_downcase(dns_name_t *source, dns_name_t *name,
 876                   isc_buffer_t *target);
 877 /*
 878  * Downcase 'source'.
 879  *
 880  * Requires:
 881  *
 882  *      'source' and 'name' are valid names.
 883  *
 884  *      If source == name, then
 885  *
 886  *              'source' must not be read-only
 887  *
 888  *      Otherwise,
 889  *
 890  *              'target' is a valid buffer or 'target' is NULL and
 891  *              'name' has a dedicated buffer.
 892  *
 893  * Returns:
 894  *      ISC_R_SUCCESS
 895  *      ISC_R_NOSPACE
 896  *
 897  * Note: if source == name, then the result will always be ISC_R_SUCCESS.
 898  */
 899
 900 isc_result_t
 901 dns_name_concatenate(dns_name_t *prefix, dns_name_t *suffix,
 902                      dns_name_t *name, isc_buffer_t *target);
 903 /*
 904  *      Concatenate 'prefix' and 'suffix'.
 905  *
 906  * Requires:
 907  *
 908  *      'prefix' is a valid name or NULL.
 909  *
 910  *      'suffix' is a valid name or NULL.
 911  *
 912  *      'name' is a valid name or NULL.
 913  *
 914  *      'target' is a valid buffer or 'target' is NULL and 'name' has
 915  *      a dedicated buffer.
 916  *
 917  *      If 'prefix' is absolute, 'suffix' must be NULL or the empty name.
 918  *
 919  * Ensures:
 920  *
 921  *      On success,
 922  *              If 'target' is not NULL and 'name' is not NULL, then 'name'
 923  *              is attached to it.
 924  *
 925  *              The used space in target is updated.
 926  *
 927  * Returns:
 928  *      ISC_R_SUCCESS
 929  *      ISC_R_NOSPACE
 930  *      DNS_R_NAMETOOLONG
 931  */
 932
 933 void
 934 dns_name_split(dns_name_t *name, unsigned int suffixlabels,
 935                dns_name_t *prefix, dns_name_t *suffix);
 936 /*
 937  *
 938  * Split 'name' into two pieces on a label boundary.
 939  *
 940  * Notes:
 941  *      'name' is split such that 'suffix' holds the most significant
 942  *      'suffixlabels' labels.  All other labels are stored in 'prefix'.
 943  *
 944  *      Copying name data is avoided as much as possible, so 'prefix'
 945  *      and 'suffix' will end up pointing at the data for 'name'.
 946  *
 947  *      It is legitimate to pass a 'prefix' or 'suffix' that has
 948  *      its name data stored someplace other than the dedicated buffer.
 949  *      This is useful to avoid name copying in the calling function.
 950  *
 951  *      It is also legitimate to pass a 'prefix' or 'suffix' that is
 952  *      the same dns_name_t as 'name'.
 953  *
 954  * Requires:
 955  *      'name' is a valid name.
 956  *
 957  *      'suffixlabels' cannot exceed the number of labels in 'name'.
 958  *
 959  *      'prefix' is a valid name or NULL, and cannot be read-only.
 960  *
 961  *      'suffix' is a valid name or NULL, and cannot be read-only.
 962  *
 963  *      If non-NULL, 'prefix' and 'suffix' must have dedicated buffers.
 964  *
 965  *      'prefix' and 'suffix' cannot point to the same buffer.
 966  *
 967  * Ensures:
 968  *
 969  *      On success:
 970  *              If 'prefix' is not NULL it will contain the least significant
 971  *              labels.
 972  *
 973  *              If 'suffix' is not NULL it will contain the most significant
 974  *              labels.  dns_name_countlabels(suffix) will be equal to
 975  *              suffixlabels.
 976  *
 977  *      On failure:
 978  *              Either 'prefix' or 'suffix' is invalidated (depending
 979  *              on which one the problem was encountered with).
 980  *
 981  * Returns:
 982  *      ISC_R_SUCCESS   No worries.  (This function should always success).
 983  */
 984
 985 isc_result_t
 986 dns_name_dup(dns_name_t *source, isc_mem_t *mctx, dns_name_t *target);
 987 /*
 988  * Make 'target' a dynamically allocated copy of 'source'.
 989  *
 990  * Requires:
 991  *
 992  *      'source' is a valid non-empty name.
 993  *
 994  *      'target' is a valid name that is not read-only.
 995  *
 996  *      'mctx' is a valid memory context.
 997  */
 998
 999 isc_result_t
1000 dns_name_dupwithoffsets(dns_name_t *source, isc_mem_t *mctx,
1001                         dns_name_t *target);
1002 /*
1003  * Make 'target' a read-only dynamically allocated copy of 'source'.
1004  * 'target' will also have a dynamically allocated offsets table.
1005  *
1006  * Requires:
1007  *
1008  *      'source' is a valid non-empty name.
1009  *
1010  *      'target' is a valid name that is not read-only.
1011  *
1012  *      'target' has no offsets table.
1013  *
1014  *      'mctx' is a valid memory context.
1015  */
1016
1017 void
1018 dns_name_free(dns_name_t *name, isc_mem_t *mctx);
1019 /*
1020  * Free 'name'.
1021  *
1022  * Requires:
1023  *
1024  *      'name' is a valid name created previously in 'mctx' by dns_name_dup().
1025  *
1026  *      'mctx' is a valid memory context.
1027  *
1028  * Ensures:
1029  *
1030  *      All dynamic resources used by 'name' are freed and the name is
1031  *      invalidated.
1032  */
1033
1034 isc_result_t
1035 dns_name_digest(dns_name_t *name, dns_digestfunc_t digest, void *arg);
1036 /*
1037  * Send 'name' in DNSSEC canonical form to 'digest'.
1038  *
1039  * Requires:
1040  *
1041  *      'name' is a valid name.
1042  *
1043  *      'digest' is a valid dns_digestfunc_t.
1044  *
1045  * Ensures:
1046  *
1047  *      If successful, the DNSSEC canonical form of 'name' will have been
1048  *      sent to 'digest'.
1049  *
1050  *      If digest() returns something other than ISC_R_SUCCESS, that result
1051  *      will be returned as the result of dns_name_digest().
1052  *
1053  * Returns:
1054  *
1055  *      ISC_R_SUCCESS
1056  *
1057  *      Many other results are possible if not successful.
1058  *
1059  */
1060
1061 isc_boolean_t
1062 dns_name_dynamic(dns_name_t *name);
1063 /*
1064  * Returns whether there is dynamic memory associated with this name.
1065  *
1066  * Requires:
1067  *
1068  *      'name' is a valid name.
1069  *
1070  * Returns:
1071  *
1072  *      'ISC_TRUE' if the name is dynamic othewise 'ISC_FALSE'.
1073  */
1074
1075 isc_result_t
1076 dns_name_print(dns_name_t *name, FILE *stream);
1077 /*
1078  * Print 'name' on 'stream'.
1079  *
1080  * Requires:
1081  *
1082  *      'name' is a valid name.
1083  *
1084  *      'stream' is a valid stream.
1085  *
1086  * Returns:
1087  *
1088  *      ISC_R_SUCCESS
1089  *
1090  *      Any error that dns_name_totext() can return.
1091  */
1092
1093 void
1094 dns_name_format(dns_name_t *name, char *cp, unsigned int size);
1095 /*
1096  * Format 'name' as text appropriate for use in log messages.
1097  *
1098  * Store the formatted name at 'cp', writing no more than
1099  * 'size' bytes.  The resulting string is guaranteed to be
1100  * null terminated.
1101  *
1102  * The formatted name will have a terminating dot only if it is
1103  * the root.
1104  *
1105  * This function cannot fail, instead any errors are indicated
1106  * in the returned text.
1107  *
1108  * Requires:
1109  *
1110  *      'name' is a valid name.
1111  *
1112  *      'cp' points a valid character array of size 'size'.
1113  *
1114  *      'size' > 0.
1115  *
1116  */
1117
1118 #define DNS_NAME_FORMATSIZE (DNS_NAME_MAXTEXT + 1)
1119 /*
1120  * Suggested size of buffer passed to dns_name_format().
1121  * Includes space for the terminating NULL.
1122  */
1123
1124 isc_result_t
1125 dns_name_copy(dns_name_t *source, dns_name_t *dest, isc_buffer_t *target);
1126 /*
1127  * Makes 'dest' refer to a copy of the name in 'source'.  The data are
1128  * either copied to 'target' or the dedicated buffer in 'dest'.
1129  *
1130  * Requires:
1131  *      'source' is a valid name.
1132  *
1133  *      'dest' is an initialized name with a dedicated buffer.
1134  *
1135  *      'target' is NULL or an initialized buffer.
1136  *
1137  *      Either dest has a dedicated buffer or target != NULL.
1138  *
1139  * Ensures:
1140  *
1141  *      On success, the used space in target is updated.
1142  *
1143  * Returns:
1144  *      ISC_R_SUCCESS
1145  *      ISC_R_NOSPACE
1146  */
1147
1148 isc_boolean_t
1149 dns_name_ishostname(const dns_name_t *name, isc_boolean_t wildcard);
1150 /*
1151  * Return if 'name' is a valid hostname.  RFC 952 / RFC 1123.
1152  * If 'wildcard' is ISC_TRUE then allow the first label of name to
1153  * be a wildcard.
1154  * The root is also accepted.
1155  *
1156  * Requires:
1157  *      'name' to be valid.
1158  */
1159
1160
1161 isc_boolean_t
1162 dns_name_ismailbox(const dns_name_t *name);
1163 /*
1164  * Return if 'name' is a valid mailbox.  RFC 821.
1165  *
1166  * Requires:
1167  *      'name' to be valid.
1168  */
1169
1170 ISC_LANG_ENDDECLS
1171
1172 /***
1173  *** High Peformance Macros
1174  ***/
1175
1176 /*
1177  * WARNING:  Use of these macros by applications may require recompilation
1178  *           of the application in some situations where calling the function
1179  *           would not.
1180  *
1181  * WARNING:  No assertion checking is done for these macros.
1182  */
1183
1184 #define DNS_NAME_INIT(n, o) \
1185 do { \
1186         (n)->magic = DNS_NAME_MAGIC; \
1187         (n)->ndata = NULL; \
1188         (n)->length = 0; \
1189         (n)->labels = 0; \
1190         (n)->attributes = 0; \
1191         (n)->offsets = (o); \
1192         (n)->buffer = NULL; \
1193         ISC_LINK_INIT((n), link); \
1194         ISC_LIST_INIT((n)->list); \
1195 } while (0)
1196
1197 #define DNS_NAME_RESET(n) \
1198 do { \
1199         (n)->ndata = NULL; \
1200         (n)->length = 0; \
1201         (n)->labels = 0; \
1202         (n)->attributes &= ~DNS_NAMEATTR_ABSOLUTE; \
1203         if ((n)->buffer != NULL) \
1204                 isc_buffer_clear((n)->buffer); \
1205 } while (0)
1206
1207 #define DNS_NAME_SETBUFFER(n, b) \
1208         (n)->buffer = (b)
1209
1210 #define DNS_NAME_ISABSOLUTE(n) \
1211         (((n)->attributes & DNS_NAMEATTR_ABSOLUTE) != 0 ? ISC_TRUE : ISC_FALSE)
1212
1213 #define DNS_NAME_COUNTLABELS(n) \
1214         ((n)->labels)
1215
1216 #define DNS_NAME_TOREGION(n, r) \
1217 do { \
1218         (r)->base = (n)->ndata; \
1219         (r)->length = (n)->length; \
1220 } while (0)
1221
1222 #define DNS_NAME_SPLIT(n, l, p, s) \
1223 do { \
1224         dns_name_t *_n = (n); \
1225         dns_name_t *_p = (p); \
1226         dns_name_t *_s = (s); \
1227         unsigned int _l = (l); \
1228         if (_p != NULL) \
1229                 dns_name_getlabelsequence(_n, 0, _n->labels - _l, _p); \
1230         if (_s != NULL) \
1231                 dns_name_getlabelsequence(_n, _n->labels - _l, _l, _s); \
1232 } while (0)
1233
1234 #ifdef DNS_NAME_USEINLINE
1235
1236 #define dns_name_init(n, o)             DNS_NAME_INIT(n, o)
1237 #define dns_name_reset(n)               DNS_NAME_RESET(n)
1238 #define dns_name_setbuffer(n, b)        DNS_NAME_SETBUFFER(n, b)
1239 #define dns_name_countlabels(n)         DNS_NAME_COUNTLABELS(n)
1240 #define dns_name_isabsolute(n)          DNS_NAME_ISABSOLUTE(n)
1241 #define dns_name_toregion(n, r)         DNS_NAME_TOREGION(n, r)
1242 #define dns_name_split(n, l, p, s)      DNS_NAME_SPLIT(n, l, p, s)
1243
1244 #endif /* DNS_NAME_USEINLINE */
1245
1246 #endif /* DNS_NAME_H */