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