| Current File : //usr/include/bind9/dns/name.h |
/*
* Copyright (C) Internet Systems Consortium, Inc. ("ISC")
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, you can obtain one at https://mozilla.org/MPL/2.0/.
*
* See the COPYRIGHT file distributed with this work for additional
* information regarding copyright ownership.
*/
#ifndef DNS_NAME_H
#define DNS_NAME_H 1
/*****
***** Module Info
*****/
/*! \file dns/name.h
* \brief
* 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:
*\li Clients of this module must impose any required synchronization.
*
* Reliability:
*\li This module deals with low-level byte streams. Errors in any of
* the functions are likely to crash the server or corrupt memory.
*
* Resources:
*\li None.
*
* Security:
*
*\li *** WARNING ***
*
*\li dns_name_fromwire() deals with raw network data. An error in
* this routine could result in the failure or hijacking of the server.
*
* Standards:
*\li RFC1035
*\li Draft EDNS0 (0)
*\li Draft Binary Labels (2)
*
*/
/***
*** Imports
***/
#include <stdio.h>
#include <inttypes.h>
#include <stdbool.h>
#include <isc/ht.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.
*****/
/***
*** 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;
isc_ht_t *ht;
};
#define DNS_NAME_MAGIC ISC_MAGIC('D','N','S','n')
#define DNS_NAMEATTR_ABSOLUTE 0x00000001
#define DNS_NAMEATTR_READONLY 0x00000002
#define DNS_NAMEATTR_DYNAMIC 0x00000004
#define DNS_NAMEATTR_DYNOFFSETS 0x00000008
#define DNS_NAMEATTR_NOCOMPRESS 0x00000010
/*
* Attributes below 0x0100 reserved for name.c usage.
*/
#define DNS_NAMEATTR_CACHE 0x00000100 /*%< Used by resolver. */
#define DNS_NAMEATTR_ANSWER 0x00000200 /*%< Used by resolver. */
#define DNS_NAMEATTR_NCACHE 0x00000400 /*%< Used by resolver. */
#define DNS_NAMEATTR_CHAINING 0x00000800 /*%< Used by resolver. */
#define DNS_NAMEATTR_CHASE 0x00001000 /*%< Used by resolver. */
#define DNS_NAMEATTR_WILDCARD 0x00002000 /*%< Used by server. */
#define DNS_NAMEATTR_PREREQUISITE 0x00004000 /*%< Used by client. */
#define DNS_NAMEATTR_UPDATE 0x00008000 /*%< Used by client. */
#define DNS_NAMEATTR_HASUPDATEREC 0x00010000 /*%< Used by client. */
/*
* Various flags.
*/
#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. */
#define DNS_NAME_CHECKMX 0x0010 /*%< Used by rdata. */
#define DNS_NAME_CHECKMXFAIL 0x0020 /*%< Used by rdata. */
LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_rootname;
LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_wildcardname;
/*%<
* DNS_NAME_INITNONABSOLUTE and DNS_NAME_INITABSOLUTE are macros for
* initializing dns_name_t structures.
*
* Note[1]: 'length' is set to (sizeof(A) - 1) in DNS_NAME_INITNONABSOLUTE
* and sizeof(A) in DNS_NAME_INITABSOLUTE to allow C strings to be used
* to initialize 'ndata'.
*
* Note[2]: The final value of offsets for DNS_NAME_INITABSOLUTE should
* match (sizeof(A) - 1) which is the offset of the root label.
*
* Typical usage:
* unsigned char data[] = "\005value";
* unsigned char offsets[] = { 0 };
* dns_name_t value = DNS_NAME_INITNONABSOLUTE(data, offsets);
*
* unsigned char data[] = "\005value";
* unsigned char offsets[] = { 0, 6 };
* dns_name_t value = DNS_NAME_INITABSOLUTE(data, offsets);
*/
#define DNS_NAME_INITNONABSOLUTE(A,B) { \
DNS_NAME_MAGIC, \
A, (sizeof(A) - 1), sizeof(B), \
DNS_NAMEATTR_READONLY, \
B, NULL, { (void *)-1, (void *)-1}, \
{NULL, NULL}, NULL \
}
#define DNS_NAME_INITABSOLUTE(A,B) { \
DNS_NAME_MAGIC, \
A, sizeof(A), sizeof(B), \
DNS_NAMEATTR_READONLY | DNS_NAMEATTR_ABSOLUTE, \
B, NULL, { (void *)-1, (void *)-1}, \
{NULL, NULL}, NULL \
}
#define DNS_NAME_INITEMPTY { \
DNS_NAME_MAGIC, NULL, 0, 0, 0, NULL, NULL, \
{ (void *)-1, (void *)-1 }, { NULL, NULL }, NULL \
}
/*%
* Standard size of a wire format name
*/
#define DNS_NAME_MAXWIRE 255
/*
* Text output filter procedure.
* 'target' is the buffer to be converted. The region to be converted
* is from 'buffer'->base + 'used_org' to the end of the used region.
*/
typedef isc_result_t (*dns_name_totextfilter_t)(isc_buffer_t *target,
unsigned int used_org,
bool absolute);
/***
*** Initialization
***/
void
dns_name_init(dns_name_t *name, unsigned char *offsets);
/*%<
* Initialize 'name'.
*
* Notes:
* \li '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:
* \li 'name' is not NULL and points to a struct dns_name.
*
* \li offsets == NULL or offsets is a dns_offsets_t.
*
* Ensures:
* \li 'name' is a valid name.
* \li dns_name_countlabels(name) == 0
* \li dns_name_isabsolute(name) == false
*/
void
dns_name_reset(dns_name_t *name);
/*%<
* Reinitialize 'name'.
*
* Notes:
* \li This function distinguishes itself from dns_name_init() in two
* key ways:
*
* \li + 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.
*
* \li + Of the attributes associated with 'name', all are retained except
* DNS_NAMEATTR_ABSOLUTE.
*
* Requires:
* \li 'name' is a valid name.
*
* Ensures:
* \li 'name' is a valid name.
* \li dns_name_countlabels(name) == 0
* \li dns_name_isabsolute(name) == false
*/
void
dns_name_invalidate(dns_name_t *name);
/*%<
* Make 'name' invalid.
*
* Requires:
* \li 'name' is a valid name.
*
* Ensures:
* \li If assertion checking is enabled, future attempts to use 'name'
* without initializing it will cause an assertion failure.
*
* \li If the name had a dedicated buffer, that association is ended.
*/
bool
dns_name_isvalid(const dns_name_t *name);
/*%<
* Check whether 'name' points to a valid dns_name
*/
/***
*** Dedicated Buffers
***/
void
dns_name_setbuffer(dns_name_t *name, isc_buffer_t *buffer);
/*%<
* Dedicate a buffer for use with 'name'.
*
* Notes:
* \li Specification of a target buffer in dns_name_fromwire(),
* dns_name_fromtext(), and dns_name_concatenate() is optional if
* 'name' has a dedicated buffer.
*
* \li The caller must not write to buffer until the name has been
* invalidated or is otherwise known not to be in use.
*
* \li 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:
* \li 'name' is a valid name.
*
* \li 'buffer' is a valid binary buffer and 'name' doesn't have a
* dedicated buffer already, or 'buffer' is NULL.
*/
bool
dns_name_hasbuffer(const dns_name_t *name);
/*%<
* Does 'name' have a dedicated buffer?
*
* Requires:
* \li 'name' is a valid name.
*
* Returns:
* \li true 'name' has a dedicated buffer.
* \li false 'name' does not have a dedicated buffer.
*/
/***
*** Properties
***/
bool
dns_name_isabsolute(const dns_name_t *name);
/*%<
* Does 'name' end in the root label?
*
* Requires:
* \li 'name' is a valid name
*
* Returns:
* \li TRUE The last label in 'name' is the root label.
* \li FALSE The last label in 'name' is not the root label.
*/
bool
dns_name_iswildcard(const dns_name_t *name);
/*%<
* Is 'name' a wildcard name?
*
* Requires:
* \li 'name' is a valid name
*
* \li dns_name_countlabels(name) > 0
*
* Returns:
* \li TRUE The least significant label of 'name' is '*'.
* \li FALSE The least significant label of 'name' is not '*'.
*/
unsigned int
dns_name_hash(dns_name_t *name, bool case_sensitive);
/*%<
* Provide a hash value for 'name'.
*
* Note: if 'case_sensitive' is false, then names which differ only in
* case will have the same hash value.
*
* Requires:
* \li 'name' is a valid name
*
* Returns:
* \li A hash value
*/
unsigned int
dns_name_fullhash(dns_name_t *name, bool 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 false, then names which differ only in
* case will have the same hash value.
*
* Requires:
*\li 'name' is a valid name
*
* Returns:
*\li A hash value
*/
unsigned int
dns_name_hashbylabel(dns_name_t *name, bool case_sensitive);
/*%<
* Provide a hash value for 'name', where the hash value is the sum
* of the hash values of each label. This function should only be used
* when incremental hashing is necessary, for example, during RBT
* traversal. It is not currently used in BIND. Generally,
* dns_name_fullhash() is the correct function to use for name
* hashing.
*
* Note: if 'case_sensitive' is false, then names which differ only in
* case will have the same hash value.
*
* Requires:
*\li 'name' is a valid name
*
* Returns:
*\li 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:
*\li 'name1' is a valid name
*
*\li dns_name_countlabels(name1) > 0
*
*\li 'name2' is a valid name
*
*\li dns_name_countlabels(name2) > 0
*
*\li orderp and nlabelsp are valid pointers.
*
*\li Either name1 is absolute and name2 is absolute, or neither is.
*
* Ensures:
*
*\li *orderp is < 0 if name1 < name2, 0 if name1 = name2, > 0 if
* name1 > name2.
*
*\li *nlabelsp is the number of common significant labels.
*
* Returns:
*\li dns_namereln_none There's no hierarchical relationship
* between name1 and name2.
*\li dns_namereln_contains name1 properly contains name2; i.e.
* name2 is a proper subdomain of name1.
*\li dns_namereln_subdomain name1 is a proper subdomain of name2.
*\li dns_namereln_equal name1 and name2 are equal.
*\li 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:
* \li 'name1' is a valid name
*
* \li 'name2' is a valid name
*
* \li Either name1 is absolute and name2 is absolute, or neither is.
*
* Returns:
* \li < 0 'name1' is less than 'name2'
* \li 0 'name1' is equal to 'name2'
* \li > 0 'name1' is greater than 'name2'
*/
bool
dns_name_equal(const dns_name_t *name1, const dns_name_t *name2);
/*%<
* Are 'name1' and 'name2' equal?
*
* Notes:
* \li Because it only needs to test for equality, dns_name_equal() can be
* significantly faster than dns_name_fullcompare() or dns_name_compare().
*
* \li Offsets tables are not used in the comparison.
*
* \li 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:
* \li 'name1' is a valid name
*
* \li 'name2' is a valid name
*
* \li Either name1 is absolute and name2 is absolute, or neither is.
*
* Returns:
* \li true 'name1' and 'name2' are equal
* \li false 'name1' and 'name2' are not equal
*/
bool
dns_name_caseequal(const dns_name_t *name1, const dns_name_t *name2);
/*%<
* Case sensitive version of dns_name_equal().
*/
int
dns_name_rdatacompare(const dns_name_t *name1, const dns_name_t *name2);
/*%<
* Compare two names as if they are part of rdata in DNSSEC canonical
* form.
*
* Requires:
* \li 'name1' is a valid absolute name
*
* \li dns_name_countlabels(name1) > 0
*
* \li 'name2' is a valid absolute name
*
* \li dns_name_countlabels(name2) > 0
*
* Returns:
* \li < 0 'name1' is less than 'name2'
* \li 0 'name1' is equal to 'name2'
* \li > 0 'name1' is greater than 'name2'
*/
bool
dns_name_issubdomain(const dns_name_t *name1, const dns_name_t *name2);
/*%<
* Is 'name1' a subdomain of 'name2'?
*
* Notes:
* \li name1 is a subdomain of name2 if name1 is contained in name2, or
* name1 equals name2.
*
* \li 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:
* \li 'name1' is a valid name
*
* \li 'name2' is a valid name
*
* \li Either name1 is absolute and name2 is absolute, or neither is.
*
* Returns:
* \li TRUE 'name1' is a subdomain of 'name2'
* \li FALSE 'name1' is not a subdomain of 'name2'
*/
bool
dns_name_matcheswildcard(const dns_name_t *name, const dns_name_t *wname);
/*%<
* Does 'name' match the wildcard specified in 'wname'?
*
* Notes:
* \li name matches the wildcard specified in wname if all labels
* following the wildcard in wname are identical to the same number
* of labels at the end of name.
*
* \li 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:
* \li 'name' is a valid name
*
* \li dns_name_countlabels(name) > 0
*
* \li 'wname' is a valid name
*
* \li dns_name_countlabels(wname) > 0
*
* \li dns_name_iswildcard(wname) is true
*
* \li Either name is absolute and wname is absolute, or neither is.
*
* Returns:
* \li TRUE 'name' matches the wildcard specified in 'wname'
* \li FALSE 'name' does not match the wildcard specified in 'wname'
*/
/***
*** Labels
***/
unsigned int
dns_name_countlabels(const dns_name_t *name);
/*%<
* How many labels does 'name' have?
*
* Notes:
* \li In this case, as in other places, a 'label' is an ordinary label.
*
* Requires:
* \li 'name' is a valid name
*
* Ensures:
* \li The result is <= 128.
*
* Returns:
* \li The number of labels in 'name'.
*/
void
dns_name_getlabel(const dns_name_t *name, unsigned int n, dns_label_t *label);
/*%<
* Make 'label' refer to the 'n'th least significant label of 'name'.
*
* Notes:
* \li Numbering starts at 0.
*
* \li Given "rc.vix.com.", the label 0 is "rc", and label 3 is the
* root label.
*
* \li 'label' refers to the same memory as 'name', so 'name' must not
* be changed while 'label' is still in use.
*
* Requires:
* \li n < dns_name_countlabels(name)
*/
void
dns_name_getlabelsequence(const dns_name_t *source, unsigned int first,
unsigned int n, dns_name_t *target);
/*%<
* Make 'target' refer to the 'n' labels including and following 'first'
* in 'source'.
*
* Notes:
* \li Numbering starts at 0.
*
* \li Given "rc.vix.com.", the label 0 is "rc", and label 3 is the
* root label.
*
* \li 'target' refers to the same memory as 'source', so 'source'
* must not be changed while 'target' is still in use.
*
* Requires:
* \li 'source' and 'target' are valid names.
*
* \li first < dns_name_countlabels(name)
*
* \li first + n <= dns_name_countlabels(name)
*/
void
dns_name_clone(const dns_name_t *source, dns_name_t *target);
/*%<
* Make 'target' refer to the same name as 'source'.
*
* Notes:
*
* \li 'target' refers to the same memory as 'source', so 'source'
* must not be changed while 'target' is still in use.
*
* \li This call is functionally equivalent to:
*
* \code
* dns_name_getlabelsequence(source, 0,
* dns_name_countlabels(source),
* target);
* \endcode
*
* but is more efficient. Also, dns_name_clone() works even if 'source'
* is empty.
*
* Requires:
*
* \li 'source' is a valid name.
*
* \li 'target' is a valid name that is not read-only.
*/
/***
*** Conversions
***/
void
dns_name_fromregion(dns_name_t *name, const isc_region_t *r);
/*%<
* Make 'name' refer to region 'r'.
*
* Note:
* \li If the conversion encounters a root label before the end of the
* region the conversion stops and the length is set to the length
* so far converted. A maximum of 255 bytes is converted.
*
* Requires:
* \li The data in 'r' is a sequence of one or more type 00 or type 01000001
* labels.
*/
void
dns_name_toregion(dns_name_t *name, isc_region_t *r);
/*%<
* Make 'r' refer to 'name'.
*
* Requires:
*
* \li 'name' is a valid name.
*
* \li 'r' is a valid region.
*/
isc_result_t
dns_name_fromwire(dns_name_t *name, isc_buffer_t *source,
dns_decompress_t *dctx, unsigned int options,
isc_buffer_t *target);
/*%<
* Copy the possibly-compressed name at source (active region) into target,
* decompressing it.
*
* Notes:
* \li Decompression policy is controlled by 'dctx'.
*
* \li If DNS_NAME_DOWNCASE is set, any uppercase letters in 'source' will be
* downcased when they are copied into 'target'.
*
* Security:
*
* \li *** WARNING ***
*
* \li This routine will often be used when 'source' contains raw network
* data. A programming error in this routine could result in a denial
* of service, or in the hijacking of the server.
*
* Requires:
*
* \li 'name' is a valid name.
*
* \li 'source' is a valid buffer and the first byte of the active
* region should be the first byte of a DNS wire format domain name.
*
* \li 'target' is a valid buffer or 'target' is NULL and 'name' has
* a dedicated buffer.
*
* \li 'dctx' is a valid decompression context.
*
* Ensures:
*
* If result is success:
* \li If 'target' is not NULL, 'name' is attached to it.
*
* \li Uppercase letters are downcased in the copy iff
* DNS_NAME_DOWNCASE is set in options.
*
* \li The current location in source is advanced, and the used space
* in target is updated.
*
* Result:
* \li Success
* \li Bad Form: Label Length
* \li Bad Form: Unknown Label Type
* \li Bad Form: Name Length
* \li Bad Form: Compression type not allowed
* \li Bad Form: Bad compression pointer
* \li Bad Form: Input too short
* \li Resource Limit: Too many compression pointers
* \li Resource Limit: Not enough space in buffer
*/
isc_result_t
dns_name_towire(const dns_name_t *name, dns_compress_t *cctx,
isc_buffer_t *target);
/*%<
* Convert 'name' into wire format, compressing it as specified by the
* compression context 'cctx', and storing the result in 'target'.
*
* Notes:
* \li If the compression context allows global compression, then the
* global compression table may be updated.
*
* Requires:
* \li 'name' is a valid name
*
* \li dns_name_countlabels(name) > 0
*
* \li dns_name_isabsolute(name) == TRUE
*
* \li target is a valid buffer.
*
* \li Any offsets specified in a global compression table are valid
* for buffer.
*
* Ensures:
*
* If the result is success:
*
* \li The used space in target is updated.
*
* Returns:
* \li Success
* \li Resource Limit: Not enough space in buffer
*/
isc_result_t
dns_name_fromtext(dns_name_t *name, isc_buffer_t *source,
const dns_name_t *origin, unsigned int options,
isc_buffer_t *target);
/*%<
* Convert the textual representation of a DNS name at source
* into uncompressed wire form stored in target.
*
* Notes:
* \li Relative domain names will have 'origin' appended to them
* unless 'origin' is NULL, in which case relative domain names
* will remain relative.
*
* \li If DNS_NAME_DOWNCASE is set in 'options', any uppercase letters
* in 'source' will be downcased when they are copied into 'target'.
*
* Requires:
*
* \li 'name' is a valid name.
*
* \li 'source' is a valid buffer.
*
* \li 'target' is a valid buffer or 'target' is NULL and 'name' has
* a dedicated buffer.
*
* Ensures:
*
* If result is success:
* \li If 'target' is not NULL, 'name' is attached to it.
*
* \li Uppercase letters are downcased in the copy iff
* DNS_NAME_DOWNCASE is set in 'options'.
*
* \li The current location in source is advanced, and the used space
* in target is updated.
*
* Result:
*\li #ISC_R_SUCCESS
*\li #DNS_R_EMPTYLABEL
*\li #DNS_R_LABELTOOLONG
*\li #DNS_R_BADESCAPE
*\li #DNS_R_BADDOTTEDQUAD
*\li #ISC_R_NOSPACE
*\li #ISC_R_UNEXPECTEDEND
*/
#define DNS_NAME_OMITFINALDOT 0x01U
#define DNS_NAME_MASTERFILE 0x02U /* escape $ and @ */
isc_result_t
dns_name_toprincipal(const dns_name_t *name, isc_buffer_t *target);
isc_result_t
dns_name_totext(const dns_name_t *name, bool omit_final_dot,
isc_buffer_t *target);
isc_result_t
dns_name_totext2(const dns_name_t *name, unsigned int options,
isc_buffer_t *target);
/*%<
* Convert 'name' into text format, storing the result in 'target'.
*
* Notes:
*\li If 'omit_final_dot' is true, then the final '.' in absolute
* names other than the root name will be omitted.
*
*\li If DNS_NAME_OMITFINALDOT is set in options, then the final '.'
* in absolute names other than the root name will be omitted.
*
*\li If DNS_NAME_MASTERFILE is set in options, '$' and '@' will also
* be escaped.
*
*\li If dns_name_countlabels == 0, the name will be "@", representing the
* current origin as described by RFC1035.
*
*\li The name is not NUL terminated.
*
* Requires:
*
*\li 'name' is a valid name
*
*\li 'target' is a valid buffer.
*
*\li if dns_name_isabsolute == FALSE, then omit_final_dot == FALSE
*
* Ensures:
*
*\li If the result is success:
* the used space in target is updated.
*
* Returns:
*\li #ISC_R_SUCCESS
*\li #ISC_R_NOSPACE
*/
#define DNS_NAME_MAXTEXT 1023
/*%<
* The maximum length of the text representation of a domain
* name as generated by dns_name_totext(). This does not
* include space for a terminating NULL.
*
* This definition is conservative - the actual maximum
* is 1004, derived as follows:
*
* A backslash-decimal escaped character takes 4 bytes.
* A wire-encoded name can be up to 255 bytes and each
* label is one length byte + at most 63 bytes of data.
* Maximizing the label lengths gives us a name of
* three 63-octet labels, one 61-octet label, and the
* root label:
*
* 1 + 63 + 1 + 63 + 1 + 63 + 1 + 61 + 1 = 255
*
* When printed, this is (3 * 63 + 61) * 4
* bytes for the escaped label data + 4 bytes for the
* dot terminating each label = 1004 bytes total.
*/
isc_result_t
dns_name_tofilenametext(dns_name_t *name, bool omit_final_dot,
isc_buffer_t *target);
/*%<
* Convert 'name' into an alternate text format appropriate for filenames,
* storing the result in 'target'. The name data is downcased, guaranteeing
* that the filename does not depend on the case of the converted name.
*
* Notes:
*\li If 'omit_final_dot' is true, then the final '.' in absolute
* names other than the root name will be omitted.
*
*\li The name is not NUL terminated.
*
* Requires:
*
*\li 'name' is a valid absolute name
*
*\li 'target' is a valid buffer.
*
* Ensures:
*
*\li If the result is success:
* the used space in target is updated.
*
* Returns:
*\li #ISC_R_SUCCESS
*\li #ISC_R_NOSPACE
*/
isc_result_t
dns_name_downcase(dns_name_t *source, dns_name_t *name,
isc_buffer_t *target);
/*%<
* Downcase 'source'.
*
* Requires:
*
*\li 'source' and 'name' are valid names.
*
*\li If source == name, then
* 'source' must not be read-only
*
*\li Otherwise,
* 'target' is a valid buffer or 'target' is NULL and
* 'name' has a dedicated buffer.
*
* Returns:
*\li #ISC_R_SUCCESS
*\li #ISC_R_NOSPACE
*
* Note: if source == name, then the result will always be ISC_R_SUCCESS.
*/
isc_result_t
dns_name_concatenate(dns_name_t *prefix, dns_name_t *suffix,
dns_name_t *name, isc_buffer_t *target);
/*%<
* Concatenate 'prefix' and 'suffix'.
*
* Requires:
*
*\li 'prefix' is a valid name or NULL.
*
*\li 'suffix' is a valid name or NULL.
*
*\li 'name' is a valid name or NULL.
*
*\li 'target' is a valid buffer or 'target' is NULL and 'name' has
* a dedicated buffer.
*
*\li If 'prefix' is absolute, 'suffix' must be NULL or the empty name.
*
* Ensures:
*
*\li On success,
* If 'target' is not NULL and 'name' is not NULL, then 'name'
* is attached to it.
* The used space in target is updated.
*
* Returns:
*\li #ISC_R_SUCCESS
*\li #ISC_R_NOSPACE
*\li #DNS_R_NAMETOOLONG
*/
void
dns_name_split(dns_name_t *name, unsigned int suffixlabels,
dns_name_t *prefix, dns_name_t *suffix);
/*%<
*
* Split 'name' into two pieces on a label boundary.
*
* Notes:
* \li 'name' is split such that 'suffix' holds the most significant
* 'suffixlabels' labels. All other labels are stored in 'prefix'.
*
*\li Copying name data is avoided as much as possible, so 'prefix'
* and 'suffix' will end up pointing at the data for 'name'.
*
*\li It is legitimate to pass a 'prefix' or 'suffix' that has
* its name data stored someplace other than the dedicated buffer.
* This is useful to avoid name copying in the calling function.
*
*\li It is also legitimate to pass a 'prefix' or 'suffix' that is
* the same dns_name_t as 'name'.
*
* Requires:
*\li 'name' is a valid name.
*
*\li 'suffixlabels' cannot exceed the number of labels in 'name'.
*
* \li 'prefix' is a valid name or NULL, and cannot be read-only.
*
*\li 'suffix' is a valid name or NULL, and cannot be read-only.
*
* Ensures:
*
*\li On success:
* If 'prefix' is not NULL it will contain the least significant
* labels.
* If 'suffix' is not NULL it will contain the most significant
* labels. dns_name_countlabels(suffix) will be equal to
* suffixlabels.
*
*\li On failure:
* Either 'prefix' or 'suffix' is invalidated (depending
* on which one the problem was encountered with).
*
* Returns:
*\li #ISC_R_SUCCESS No worries. (This function should always success).
*/
isc_result_t
dns_name_dup(const dns_name_t *source, isc_mem_t *mctx,
dns_name_t *target);
/*%<
* Make 'target' a dynamically allocated copy of 'source'.
*
* Requires:
*
*\li 'source' is a valid non-empty name.
*
*\li 'target' is a valid name that is not read-only.
*
*\li 'mctx' is a valid memory context.
*/
isc_result_t
dns_name_dupwithoffsets(dns_name_t *source, isc_mem_t *mctx,
dns_name_t *target);
/*%<
* Make 'target' a read-only dynamically allocated copy of 'source'.
* 'target' will also have a dynamically allocated offsets table.
*
* Requires:
*
*\li 'source' is a valid non-empty name.
*
*\li 'target' is a valid name that is not read-only.
*
*\li 'target' has no offsets table.
*
*\li 'mctx' is a valid memory context.
*/
void
dns_name_free(dns_name_t *name, isc_mem_t *mctx);
/*%<
* Free 'name'.
*
* Requires:
*
*\li 'name' is a valid name created previously in 'mctx' by dns_name_dup().
*
*\li 'mctx' is a valid memory context.
*
* Ensures:
*
*\li All dynamic resources used by 'name' are freed and the name is
* invalidated.
*/
isc_result_t
dns_name_digest(dns_name_t *name, dns_digestfunc_t digest, void *arg);
/*%<
* Send 'name' in DNSSEC canonical form to 'digest'.
*
* Requires:
*
*\li 'name' is a valid name.
*
*\li 'digest' is a valid dns_digestfunc_t.
*
* Ensures:
*
*\li If successful, the DNSSEC canonical form of 'name' will have been
* sent to 'digest'.
*
*\li If digest() returns something other than ISC_R_SUCCESS, that result
* will be returned as the result of dns_name_digest().
*
* Returns:
*
*\li #ISC_R_SUCCESS
*
*\li Many other results are possible if not successful.
*
*/
bool
dns_name_dynamic(dns_name_t *name);
/*%<
* Returns whether there is dynamic memory associated with this name.
*
* Requires:
*
*\li 'name' is a valid name.
*
* Returns:
*
*\li 'true' if the name is dynamic otherwise 'false'.
*/
isc_result_t
dns_name_print(dns_name_t *name, FILE *stream);
/*%<
* Print 'name' on 'stream'.
*
* Requires:
*
*\li 'name' is a valid name.
*
*\li 'stream' is a valid stream.
*
* Returns:
*
*\li #ISC_R_SUCCESS
*
*\li Any error that dns_name_totext() can return.
*/
void
dns_name_format(const dns_name_t *name, char *cp, unsigned int size);
/*%<
* Format 'name' as text appropriate for use in log messages.
*
* Store the formatted name at 'cp', writing no more than
* 'size' bytes. The resulting string is guaranteed to be
* null terminated.
*
* The formatted name will have a terminating dot only if it is
* the root.
*
* This function cannot fail, instead any errors are indicated
* in the returned text.
*
* Requires:
*
*\li 'name' is a valid name.
*
*\li 'cp' points a valid character array of size 'size'.
*
*\li 'size' > 0.
*
*/
isc_result_t
dns_name_tostring(dns_name_t *source, char **target, isc_mem_t *mctx);
/*%<
* Convert 'name' to string format, allocating sufficient memory to
* hold it (free with isc_mem_free()).
*
* Differs from dns_name_format in that it allocates its own memory.
*
* Requires:
*
*\li 'name' is a valid name.
*\li 'target' is not NULL.
*\li '*target' is NULL.
*
* Returns:
*
*\li ISC_R_SUCCESS
*\li ISC_R_NOMEMORY
*
*\li Any error that dns_name_totext() can return.
*/
isc_result_t
dns_name_fromstring(dns_name_t *target, const char *src, unsigned int options,
isc_mem_t *mctx);
isc_result_t
dns_name_fromstring2(dns_name_t *target, const char *src,
const dns_name_t *origin, unsigned int options,
isc_mem_t *mctx);
/*%<
* Convert a string to a name and place it in target, allocating memory
* as necessary. 'options' has the same semantics as that of
* dns_name_fromtext().
*
* If 'target' has a buffer then the name will be copied into it rather than
* memory being allocated.
*
* Requires:
*
* \li 'target' is a valid name that is not read-only.
* \li 'src' is not NULL.
*
* Returns:
*
*\li #ISC_R_SUCCESS
*
*\li Any error that dns_name_fromtext() can return.
*
*\li Any error that dns_name_dup() can return.
*/
isc_result_t
dns_name_settotextfilter(dns_name_totextfilter_t proc);
/*%<
* Set / clear a thread specific function 'proc' to be called at the
* end of dns_name_totext().
*
* Note: Under Windows you need to call "dns_name_settotextfilter(NULL);"
* prior to exiting the thread otherwise memory will be leaked.
* For other platforms, which are pthreads based, this is still a good
* idea but not required.
*
* Returns
*\li #ISC_R_SUCCESS
*\li #ISC_R_UNEXPECTED
*/
#define DNS_NAME_FORMATSIZE (DNS_NAME_MAXTEXT + 1)
/*%<
* Suggested size of buffer passed to dns_name_format().
* Includes space for the terminating NULL.
*/
isc_result_t
dns_name_copy(const dns_name_t *source, dns_name_t *dest, isc_buffer_t *target);
/*%<
* Makes 'dest' refer to a copy of the name in 'source'. The data are
* either copied to 'target' or the dedicated buffer in 'dest'.
*
* Requires:
* \li 'source' is a valid name.
*
* \li 'dest' is an initialized name with a dedicated buffer.
*
* \li 'target' is NULL or an initialized buffer.
*
* \li Either dest has a dedicated buffer or target != NULL.
*
* Ensures:
*
*\li On success, the used space in target is updated.
*
* Returns:
*\li #ISC_R_SUCCESS
*\li #ISC_R_NOSPACE
*/
bool
dns_name_ishostname(const dns_name_t *name, bool wildcard);
/*%<
* Return if 'name' is a valid hostname. RFC 952 / RFC 1123.
* If 'wildcard' is true then allow the first label of name to
* be a wildcard.
* The root is also accepted.
*
* Requires:
* 'name' to be valid.
*/
bool
dns_name_ismailbox(const dns_name_t *name);
/*%<
* Return if 'name' is a valid mailbox. RFC 821.
*
* Requires:
* \li 'name' to be valid.
*/
bool
dns_name_internalwildcard(const dns_name_t *name);
/*%<
* Return if 'name' contains a internal wildcard name.
*
* Requires:
* \li 'name' to be valid.
*/
void
dns_name_destroy(void);
/*%<
* Cleanup dns_name_settotextfilter() / dns_name_totext() state.
*
* This should be called as part of the final cleanup process.
*
* Note: dns_name_settotextfilter(NULL); should be called for all
* threads which have called dns_name_settotextfilter() with a
* non-NULL argument prior to calling dns_name_destroy();
*/
bool
dns_name_isdnssd(const dns_name_t *owner);
/*%<
* Determine if the 'owner' is a DNS-SD prefix.
*/
bool
dns_name_isrfc1918(const dns_name_t *owner);
/*%<
* Determine if the 'name' is in the RFC 1918 reverse namespace.
*/
bool
dns_name_isula(const dns_name_t *owner);
/*%<
* Determine if the 'name' is in the ULA reverse namespace.
*/
bool
dns_name_istat(const dns_name_t *name);
/*
* Determine if 'name' is a potential 'trust-anchor-telemetry' name.
*/
ISC_LANG_ENDDECLS
/*
*** High Performance Macros
***/
/*
* WARNING: Use of these macros by applications may require recompilation
* of the application in some situations where calling the function
* would not.
*
* WARNING: No assertion checking is done for these macros.
*/
#define DNS_NAME_INIT(n, o) \
do { \
dns_name_t *_n = (n); \
/* memset(_n, 0, sizeof(*_n)); */ \
_n->magic = DNS_NAME_MAGIC; \
_n->ndata = NULL; \
_n->length = 0; \
_n->labels = 0; \
_n->attributes = 0; \
_n->offsets = (o); \
_n->buffer = NULL; \
ISC_LINK_INIT(_n, link); \
ISC_LIST_INIT(_n->list); \
_n->ht = NULL; \
} while (0)
#define DNS_NAME_RESET(n) \
do { \
(n)->ndata = NULL; \
(n)->length = 0; \
(n)->labels = 0; \
(n)->attributes &= ~DNS_NAMEATTR_ABSOLUTE; \
if ((n)->buffer != NULL) \
isc_buffer_clear((n)->buffer); \
} while (0)
#define DNS_NAME_SETBUFFER(n, b) \
(n)->buffer = (b)
#define DNS_NAME_ISABSOLUTE(n) \
(((n)->attributes & DNS_NAMEATTR_ABSOLUTE) != 0 ? true : false)
#define DNS_NAME_COUNTLABELS(n) \
((n)->labels)
#define DNS_NAME_TOREGION(n, r) \
do { \
(r)->base = (n)->ndata; \
(r)->length = (n)->length; \
} while (0)
#define DNS_NAME_SPLIT(n, l, p, s) \
do { \
dns_name_t *_n = (n); \
dns_name_t *_p = (p); \
dns_name_t *_s = (s); \
unsigned int _l = (l); \
if (_p != NULL) \
dns_name_getlabelsequence(_n, 0, _n->labels - _l, _p); \
if (_s != NULL) \
dns_name_getlabelsequence(_n, _n->labels - _l, _l, _s); \
} while (0)
#ifdef DNS_NAME_USEINLINE
#define dns_name_init(n, o) DNS_NAME_INIT(n, o)
#define dns_name_reset(n) DNS_NAME_RESET(n)
#define dns_name_setbuffer(n, b) DNS_NAME_SETBUFFER(n, b)
#define dns_name_countlabels(n) DNS_NAME_COUNTLABELS(n)
#define dns_name_isabsolute(n) DNS_NAME_ISABSOLUTE(n)
#define dns_name_toregion(n, r) DNS_NAME_TOREGION(n, r)
#define dns_name_split(n, l, p, s) DNS_NAME_SPLIT(n, l, p, s)
#endif /* DNS_NAME_USEINLINE */
#endif /* DNS_NAME_H */