contrib/bind9/lib/dns/include/dns/name.h

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