#include <tsigkey.h>

Inheritance diagram for isc::dns::TSIGKey:

Classes
struct	TSIGKeyImpl

Public Member Functions
	TSIGKey (const Name &key_name, const Name &algorithm_name, const void *secret, size_t secret_len, size_t digestbits=0)
	Constructors, Assignment Operator and Destructor.

	TSIGKey (const std::string &str)
	Constructor from an input string.

	TSIGKey (const TSIGKey &source)
	The copy constructor.

virtual	~TSIGKey ()
	The destructor.

isc::cryptolink::HashAlgorithm	getAlgorithm () const
	Return the hash algorithm name in the form of cryptolink::HashAlgorithm.

const Name &	getAlgorithmName () const
	Return the algorithm name.

size_t	getDigestbits () const
	Return the minimum truncated length.

const Name &	getKeyName () const
	Getter Methods.

const void *	getSecret () const
	Return the value of the TSIG secret.

size_t	getSecretLength () const
	Return the length of the TSIG secret in bytes.

TSIGKey &	operator= (const TSIGKey &source)
	Assignment operator.

std::string	toText () const
	Converts the TSIGKey to a string value.

Static Public Member Functions
static const Name &	GSSTSIG_NAME ()

static const Name &	HMACMD5_NAME ()
	Well known algorithm names as defined in RFC2845 and RFC4635.

static const Name &	HMACMD5_SHORT_NAME ()

static const Name &	HMACSHA1_NAME ()

static const Name &	HMACSHA224_NAME ()

static const Name &	HMACSHA256_NAME ()

static const Name &	HMACSHA384_NAME ()

static const Name &	HMACSHA512_NAME ()

Detailed Description

TSIG key.

This class holds a TSIG key along with some related attributes as defined in RFC2845.

A TSIG key consists of the following attributes:

Key name
Hash algorithm
Digest bits
Shared secret

Implementation Notes

We may add more attributes in future versions. For example, if and when we support the TKEY protocol (RFC2930), we may need to introduce the notion of inception and expiration times. At that point we may also have to introduce a class hierarchy to handle different types of keys in a polymorphic way. At the moment we use the straightforward value-type class with minimal attributes.

In the TSIG protocol, hash algorithms are represented in the form of domain name. Our interfaces provide direct translation of this concept; for example, the constructor from parameters take a Name object to specify the algorithm. On one hand, this may be counter intuitive. An API user would rather specify "hmac-md5" instead of Name("hmac-md5.sig-alg.reg.int"). On the other hand, it may be more convenient for some kind of applications if we maintain the algorithm as the expected representation for protocol operations (such as sign and very a message). Considering these points, we adopt the interface closer to the protocol specification for now. To minimize the burden for API users, we also define a set of constants for commonly used algorithm names so that the users don't have to remember the actual domain names defined in the protocol specification. We may also have to add conversion routines between domain names and more intuitive representations (e.g. strings) for algorithms.

Definition at line 56 of file tsigkey.h.

Constructor & Destructor Documentation

◆ TSIGKey() [1/3]

isc::dns::TSIGKey::TSIGKey	(	const Name &	key_name,
		const Name &	algorithm_name,
		const void *	secret,
		size_t	secret_len,
		size_t	digestbits = 0 )

Constructors, Assignment Operator and Destructor.

Constructor from key parameters.

The algorithm_name should generally be a known algorithm to this implementation, which are defined via the static const member functions.

Other names are still accepted as long as the secret is empty (secret is null and secret_len is 0), however; in some cases we might want to treat just the pair of key name and algorithm name opaquely, e.g., when generating a response TSIG with a BADKEY error because the algorithm is unknown as specified in Section 3.2 of RFC2845 (in which case the algorithm name would be copied from the request to the response, and for that purpose it would be convenient if a TSIGKey object can hold a name for an "unknown" algorithm).

Note: RFC2845 does not specify which algorithm name should be used in such a BADKEY response. The behavior of using the same algorithm is derived from the BIND 9 implementation.

It is unlikely that a TSIG key with an unknown algorithm is of any use with actual crypto operation, so care must be taken when dealing with such keys. (The restriction for the secret will prevent accidental creation of such a dangerous key, e.g., due to misspelling in a configuration file). If the given algorithm name is unknown and non empty secret is specified, an exception of type InvalidParameter will be thrown.

secret and secret_len must be consistent in that the latter is 0 if and only if the former is null; otherwise an exception of type InvalidParameter will be thrown.

digestbits is the truncated length in bits or 0 which means no truncation and is the default. Constraints for non-zero value are in RFC 4635 section 3.1: minimum 80 or the half of the full (i.e., not truncated) length, integral number of octets (i.e., multiple of 8), and maximum the full length.

This constructor internally involves resource allocation, and if it fails, a corresponding standard exception will be thrown.

Parameters

key_name	The name of the key as a domain name.
algorithm_name	The hash algorithm used for this key in the form of domain name. For example, it can be TSIGKey::HMACSHA256_NAME() for HMAC-SHA256.
secret	Point to a binary sequence of the shared secret to be used for this key, or null if the secret is empty.
secret_len	The size of the binary data (secret) in bytes.
digestbits	The number of bits to include in the digest (0 means to include all).

Definition at line 95 of file tsigkey.cc.

References isc_throw, and isc::cryptolink::UNKNOWN_HASH.

◆ TSIGKey() [2/3]

isc::dns::TSIGKey::TSIGKey ( const std::string & str )

explicit

Constructor from an input string.

The string must be of the form: name:secret[:algorithm][:digestbits] Where "name" is a domain name for the key, "secret" is a base64 representation of the key secret, and the optional "algorithm" is an algorithm identifier as specified in RFC 4635. The default algorithm is hmac-md5.sig-alg.reg.int. "digestbits" is the minimum truncated length in bits. The default digestbits value is 0 and means truncation is forbidden.

The same restriction about the algorithm name (and secret) as that for the other constructor applies.

Since ':' is used as a separator here, it is not possible to use this constructor to create keys with a ':' character in their name.

Exceptions

InvalidParameter exception if the input string is invalid.

Parameters

str	The string to make a TSIGKey from

Definition at line 119 of file tsigkey.cc.

References isc::util::encode::decodeBase64(), isc_throw, isc::cryptolink::UNKNOWN_HASH, and isc::Exception::what().

Here is the call graph for this function:

◆ TSIGKey() [3/3]

isc::dns::TSIGKey::TSIGKey ( const TSIGKey & source )

The copy constructor.

It internally allocates a resource, and if it fails a corresponding standard exception will be thrown. This constructor never throws an exception otherwise.

Definition at line 187 of file tsigkey.cc.

◆ ~TSIGKey()

isc::dns::TSIGKey::~TSIGKey ( )

virtual

The destructor.

Definition at line 200 of file tsigkey.cc.

Member Function Documentation

◆ getAlgorithm()

isc::cryptolink::HashAlgorithm isc::dns::TSIGKey::getAlgorithm ( ) const

Return the hash algorithm name in the form of cryptolink::HashAlgorithm.

Definition at line 214 of file tsigkey.cc.

Referenced by isc::dns::TSIGContext::TSIGContextImpl::TSIGContextImpl(), and isc::dns::TSIGContext::TSIGContextImpl::createHMAC().

◆ getAlgorithmName()

const Name & isc::dns::TSIGKey::getAlgorithmName ( ) const

Return the algorithm name.

Definition at line 209 of file tsigkey.cc.

Referenced by toText().

◆ getDigestbits()

size_t isc::dns::TSIGKey::getDigestbits ( ) const

Return the minimum truncated length.

Definition at line 219 of file tsigkey.cc.

Referenced by isc::dns::TSIGContext::TSIGContextImpl::TSIGContextImpl(), and toText().

◆ getKeyName()

const Name & isc::dns::TSIGKey::getKeyName ( ) const

Getter Methods.

These methods never throw an exception.

Return the key name.

Definition at line 204 of file tsigkey.cc.

Referenced by isc::dns::TSIGKeyRing::add(), isc::d2::D2TsigKey::resetStats(), and toText().

◆ getSecret()

const void * isc::dns::TSIGKey::getSecret ( ) const

Return the value of the TSIG secret.

If it returns a non null pointer, the memory region beginning at the address returned by this method is valid up to the bytes specified by the return value of getSecretLength().

The memory region is only valid while the corresponding TSIGKey object is valid. The caller must hold the TSIGKey object while it needs to refer to the region or it must make a local copy of the region.

Definition at line 224 of file tsigkey.cc.

Referenced by isc::dns::TSIGContext::TSIGContextImpl::TSIGContextImpl(), isc::dns::TSIGContext::TSIGContextImpl::createHMAC(), and toText().

◆ getSecretLength()

size_t isc::dns::TSIGKey::getSecretLength ( ) const

Return the length of the TSIG secret in bytes.

Definition at line 229 of file tsigkey.cc.

Referenced by isc::dns::TSIGContext::TSIGContextImpl::TSIGContextImpl(), isc::dns::TSIGContext::TSIGContextImpl::createHMAC(), and toText().

◆ GSSTSIG_NAME()

const Name & isc::dns::TSIGKey::GSSTSIG_NAME ( )

static

Definition at line 346 of file tsigkey.cc.

◆ HMACMD5_NAME()

const Name & isc::dns::TSIGKey::HMACMD5_NAME ( )

static

Well known algorithm names as defined in RFC2845 and RFC4635.

Note: we begin with the "mandatory" algorithms defined in RFC4635 as a minimal initial set. We'll add others as we see the need for them.

Definition at line 304 of file tsigkey.cc.

Referenced by isc::dns::TSIGKey::TSIGKeyImpl::TSIGKeyImpl(), isc::dns::TSIGKey::TSIGKeyImpl::TSIGKeyImpl(), and isc::d2::TSIGKeyInfo::stringToAlgorithmName().

◆ HMACMD5_SHORT_NAME()

const Name & isc::dns::TSIGKey::HMACMD5_SHORT_NAME ( )

static

Definition at line 310 of file tsigkey.cc.

◆ HMACSHA1_NAME()

const Name & isc::dns::TSIGKey::HMACSHA1_NAME ( )

static

Definition at line 316 of file tsigkey.cc.

Referenced by isc::d2::TSIGKeyInfo::stringToAlgorithmName().

◆ HMACSHA224_NAME()

const Name & isc::dns::TSIGKey::HMACSHA224_NAME ( )

static

Definition at line 322 of file tsigkey.cc.

Referenced by isc::d2::TSIGKeyInfo::stringToAlgorithmName().

◆ HMACSHA256_NAME()

const Name & isc::dns::TSIGKey::HMACSHA256_NAME ( )

static

Definition at line 328 of file tsigkey.cc.

Referenced by isc::d2::TSIGKeyInfo::stringToAlgorithmName().

◆ HMACSHA384_NAME()

const Name & isc::dns::TSIGKey::HMACSHA384_NAME ( )

static

Definition at line 334 of file tsigkey.cc.

Referenced by isc::d2::TSIGKeyInfo::stringToAlgorithmName().

◆ HMACSHA512_NAME()

const Name & isc::dns::TSIGKey::HMACSHA512_NAME ( )

static

Definition at line 340 of file tsigkey.cc.

Referenced by isc::d2::TSIGKeyInfo::stringToAlgorithmName().

◆ operator=()

TSIGKey & isc::dns::TSIGKey::operator= ( const TSIGKey & source )

Assignment operator.

It internally allocates a resource, and if it fails a corresponding standard exception will be thrown. This operator never throws an exception otherwise.

This operator provides the strong exception guarantee: When an exception is thrown the content of the assignment target will be intact.

Definition at line 191 of file tsigkey.cc.

◆ toText()

std::string isc::dns::TSIGKey::toText ( ) const

Converts the TSIGKey to a string value.

The resulting string will be of the form name:secret:algorithm[:digestbits]. Where "name" is a domain name for the key, "secret" is a base64 representation of the key secret, and "algorithm" is an algorithm identifier as specified in RFC 4635. When not zero, digestbits is appended.

Returns: The string representation of the given TSIGKey.

Definition at line 234 of file tsigkey.cc.

References isc::util::encode::encodeBase64(), getAlgorithmName(), getDigestbits(), getKeyName(), getSecret(), getSecretLength(), and toText().

Referenced by toText().

Here is the call graph for this function:

The documentation for this class was generated from the following files:

Classes

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ TSIGKey() [1/3]

◆ TSIGKey() [2/3]

◆ TSIGKey() [3/3]

◆ ~TSIGKey()

Member Function Documentation

◆ getAlgorithm()

◆ getAlgorithmName()

◆ getDigestbits()

◆ getKeyName()

◆ getSecret()

◆ getSecretLength()

◆ GSSTSIG_NAME()

◆ HMACMD5_NAME()

◆ HMACMD5_SHORT_NAME()

◆ HMACSHA1_NAME()

◆ HMACSHA224_NAME()

◆ HMACSHA256_NAME()

◆ HMACSHA384_NAME()

◆ HMACSHA512_NAME()

◆ operator=()

◆ toText()