name.h

package of develop dns

/*
 * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
 * Copyright (C) 1998-2003  Internet Software Consortium.
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
 */

/* $Id: name.h,v 1.95.2.3.2.12 2004/09/08 00:29:34 marka Exp $ */

#ifndef DNS_NAME_H
#define DNS_NAME_H 1

/*****
 ***** Module Info
 *****/

/*
 * DNS Names and Labels
 *
 * Provides facilities for manipulating DNS names and labels, including
 * conversions to and from wire format and text format.
 *
 * Given the large number of names possible in a nameserver, and because
 * names occur in rdata, it was important to come up with a very efficient
 * way of storing name data, but at the same time allow names to be
 * manipulated.  The decision was to store names in uncompressed wire format,
 * and not to make them fully abstracted objects; i.e. certain parts of the
 * server know names are stored that way.  This saves a lot of memory, and
 * makes adding names to messages easy.  Having much of the server know
 * the representation would be perilous, and we certainly don't want each
 * user of names to be manipulating such a low-level structure.  This is
 * where the Names and Labels module comes in.  The module allows name or
 * label handles to be created and attached to uncompressed wire format
 * regions.  All name operations and conversions are done through these
 * handles.
 *
 * MP:
 *	Clients of this module must impose any required synchronization.
 *
 * Reliability:
 *	This module deals with low-level byte streams.  Errors in any of
 *	the functions are likely to crash the server or corrupt memory.
 *
 * Resources:
 *	None.
 *
 * Security:
 *
 *	*** WARNING ***
 *
 *	dns_name_fromwire() deals with raw network data.  An error in
 *	this routine could result in the failure or hijacking of the server.
 *
 * Standards:
 *	RFC 1035
 *	Draft EDNS0 (0)
 *	Draft Binary Labels (2)
 *
 */

/***
 *** Imports
 ***/

#include <stdio.h>

#include <isc/boolean.h>
#include <isc/lang.h>
#include <isc/magic.h>
#include <isc/region.h>		/* Required for storage size of dns_label_t. */

#include <dns/types.h>

ISC_LANG_BEGINDECLS

/*****
 ***** Labels
 *****
 ***** A 'label' is basically a region.  It contains one DNS wire format
 ***** label of type 00 (ordinary).
 *****/

/*****
 ***** Names
 *****
 ***** A 'name' is a handle to a binary region.  It contains a sequence of one
 ***** or more DNS wire format labels of type 00 (ordinary).
 ***** Note that all names are not required to end with the root label,
 ***** as they are in the actual DNS wire protocol.
 *****/

/***
 *** Compression pointer chaining limit
 ***/

#define DNS_POINTER_MAXHOPS		16

/***
 *** Types
 ***/

/*
 * Clients are strongly discouraged from using this type directly,  with
 * the exception of the 'link' and 'list' fields which may be used directly
 * for whatever purpose the client desires.
 */
struct dns_name {
	unsigned int			magic;
	unsigned char *			ndata;
	unsigned int			length;
	unsigned int			labels;
	unsigned int			attributes;
	unsigned char *			offsets;
	isc_buffer_t *			buffer;
	ISC_LINK(dns_name_t)		link;
	ISC_LIST(dns_rdataset_t)	list;
};

#define DNS_NAME_MAGIC			ISC_MAGIC('D','N','S','n')

#define DNS_NAMEATTR_ABSOLUTE		0x0001
#define DNS_NAMEATTR_READONLY		0x0002
#define DNS_NAMEATTR_DYNAMIC		0x0004
#define DNS_NAMEATTR_DYNOFFSETS		0x0008
/*
 * Attributes below 0x0100 reserved for name.c usage.
 */
#define DNS_NAMEATTR_CACHE		0x0100		/* Used by resolver. */
#define DNS_NAMEATTR_ANSWER		0x0200		/* Used by resolver. */
#define DNS_NAMEATTR_NCACHE		0x0400		/* Used by resolver. */
#define DNS_NAMEATTR_CHAINING		0x0800		/* Used by resolver. */
#define DNS_NAMEATTR_CHASE		0x1000		/* Used by resolver. */
#define DNS_NAMEATTR_WILDCARD		0x2000		/* Used by server. */

#define DNS_NAME_DOWNCASE		0x0001
#define DNS_NAME_CHECKNAMES		0x0002		/* Used by rdata. */
#define DNS_NAME_CHECKNAMESFAIL		0x0004		/* Used by rdata. */
#define DNS_NAME_CHECKREVERSE		0x0008		/* Used by rdata. */

LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_rootname;
LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_wildcardname;

/*
 * Standard size of a wire format name
 */
#define DNS_NAME_MAXWIRE 255

/***
 *** Initialization
 ***/

void
dns_name_init(dns_name_t *name, unsigned char *offsets);
/*
 * Initialize 'name'.
 *
 * Notes:
 *	'offsets' is never required to be non-NULL, but specifying a
 *	dns_offsets_t for 'offsets' will improve the performance of most
 *	name operations if the name is used more than once.
 *
 * Requires:
 *	'name' is not NULL and points to a struct dns_name.
 *
 *	offsets == NULL or offsets is a dns_offsets_t.
 *
 * Ensures:
 *	'name' is a valid name.
 *	dns_name_countlabels(name) == 0
 *	dns_name_isabsolute(name) == ISC_FALSE
 */

void
dns_name_reset(dns_name_t *name);
/*
 * Reinitialize 'name'.
 *
 * Notes:
 *	This function distinguishes itself from dns_name_init() in two
 *	key ways:
 *
 *	+ If any buffer is associated with 'name' (via dns_name_setbuffer()
 *	  or by being part of a dns_fixedname_t) the link to the buffer
 *	  is retained but the buffer itself is cleared.
 *
 *	+ Of the attributes associated with 'name', all are retained except
 *	  DNS_NAMEATTR_ABSOLUTE.
 *
 * Requires:
 *	'name' is a valid name.
 *
 * Ensures:
 *	'name' is a valid name.
 *	dns_name_countlabels(name) == 0
 *	dns_name_isabsolute(name) == ISC_FALSE
 */

void
dns_name_invalidate(dns_name_t *name);
/*
 * Make 'name' invalid.
 *
 * Requires:
 *	'name' is a valid name.
 *
 * Ensures:
 *	If assertion checking is enabled, future attempts to use 'name'
 *	without initializing it will cause an assertion failure.
 *
 *	If the name had a dedicated buffer, that association is ended.
 */


/***
 *** Dedicated Buffers
 ***/

void
dns_name_setbuffer(dns_name_t *name, isc_buffer_t *buffer);
/*
 * Dedicate a buffer for use with 'name'.
 *
 * Notes:
 *	Specification of a target buffer in dns_name_fromwire(),
 *	dns_name_fromtext(), and dns_name_concatentate() is optional if
 *	'name' has a dedicated buffer.
 *
 *	The caller must not write to buffer until the name has been
 *	invalidated or is otherwise known not to be in use.
 *
 *	If buffer is NULL and the name previously had a dedicated buffer,
 *	than that buffer is no longer dedicated to use with this name.
 *	The caller is responsible for ensuring that the storage used by
 *	the name remains valid.
 *
 * Requires:
 *	'name' is a valid name.
 *
 *	'buffer' is a valid binary buffer and 'name' doesn't have a
 *	dedicated buffer already, or 'buffer' is NULL.
 */

isc_boolean_t
dns_name_hasbuffer(const dns_name_t *name);
/*
 * Does 'name' have a dedicated buffer?
 *
 * Requires:
 *	'name' is a valid name.
 *
 * Returns:
 *	ISC_TRUE	'name' has a dedicated buffer.
 *	ISC_FALSE	'name' does not have a dedicated buffer.
 */


/***
 *** Properties
 ***/

isc_boolean_t
dns_name_isabsolute(const dns_name_t *name);
/*
 * Does 'name' end in the root label?
 *
 * Requires:
 *	'name' is a valid name
 *
 * Returns:
 *	TRUE		The last label in 'name' is the root label.
 *	FALSE		The last label in 'name' is not the root label.
 */

isc_boolean_t
dns_name_iswildcard(const dns_name_t *name);
/*
 * Is 'name' a wildcard name?
 *
 * Requires:
 *	'name' is a valid name
 *
 *	dns_name_countlabels(name) > 0
 *
 * Returns:
 *	TRUE		The least significant label of 'name' is '*'.
 *	FALSE		The least significant label of 'name' is not '*'.
 */

unsigned int
dns_name_hash(dns_name_t *name, isc_boolean_t case_sensitive);
/*
 * Provide a hash value for 'name'.
 *
 * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in
 * case will have the same hash value.
 *
 * Requires:
 *	'name' is a valid name
 *
 * Returns:
 *	A hash value
 */

unsigned int
dns_name_fullhash(dns_name_t *name, isc_boolean_t case_sensitive);
/*
 * Provide a hash value for 'name'.  Unlike dns_name_hash(), this function
 * always takes into account of the entire name to calculate the hash value.
 *
 * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in
 * case will have the same hash value.
 *
 * Requires:
 *	'name' is a valid name
 *
 * Returns:
 *	A hash value
 */

unsigned int
dns_name_hashbylabel(dns_name_t *name, isc_boolean_t case_sensitive);
/*
 * Provide a hash value for 'name', where the hash value is the sum
 * of the hash values of each label.
 *
 * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in
 * case will have the same hash value.
 *
 * Requires:
 *	'name' is a valid name
 *
 * Returns:
 *	A hash value
 */

/***
 *** Comparisons
 ***/

dns_namereln_t
dns_name_fullcompare(const dns_name_t *name1, const dns_name_t *name2,
		     int *orderp, unsigned int *nlabelsp);
/*
 * Determine the relative ordering under the DNSSEC order relation of
 * 'name1' and 'name2', and also determine the hierarchical
 * relationship of the names.
 *
 * Note: It makes no sense for one of the names to be relative and the
 * other absolute.  If both names are relative, then to be meaningfully
 * compared the caller must ensure that they are both relative to the
 * same domain.
 *
 * Requires:
 *	'name1' is a valid name
 *
 *	dns_name_countlabels(name1) > 0
 *
 *	'name2' is a valid name
 *
 *	dns_name_countlabels(name2) > 0
 *
 *	orderp and nlabelsp are valid pointers.
 *
 *	Either name1 is absolute and name2 is absolute, or neither is.
 *
 * Ensures:
 *
 *	*orderp is < 0 if name1 < name2, 0 if name1 = name2, > 0 if
 *	name1 > name2.
 *
 *	*nlabelsp is the number of common significant labels.
 *
 * Returns:
 *	dns_namereln_none		There's no hierarchical relationship
 *					between name1 and name2.
 *	dns_namereln_contains		name1 properly contains name2; i.e.
 *					name2 is a proper subdomain of name1.
 *	dns_namereln_subdomain		name1 is a proper subdomain of name2.
 *	dns_namereln_equal		name1 and name2 are equal.
 *	dns_namereln_commonancestor	name1 and name2 share a common
 *					ancestor.
 */

int
dns_name_compare(const dns_name_t *name1, const dns_name_t *name2);
/*
 * Determine the relative ordering under the DNSSEC order relation of
 * 'name1' and 'name2'.
 *
 * Note: It makes no sense for one of the names to be relative and the
 * other absolute.  If both names are relative, then to be meaningfully
 * compared the caller must ensure that they are both relative to the
 * same domain.
 *
 * Requires:
 *	'name1' is a valid name
 *
 *	'name2' is a valid name
 *
 *	Either name1 is absolute and name2 is absolute, or neither is.
 *
 * Returns:
 *	< 0		'name1' is less than 'name2'
 *	0		'name1' is equal to 'name2'
 *	> 0		'name1' is greater than 'name2'
 */