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

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