Kea  2.3.2-git
isc::dns::TSIGKey Class Reference

TSIG key. More...

#include <tsigkey.h>

+ Inheritance diagram for isc::dns::TSIGKey:

Classes

struct  TSIGKeyImpl
 

Public Member Functions

std::string toText () const
 Converts the TSIGKey to a string value. More...
 
Constructors, Assignment Operator and Destructor.
 TSIGKey (const Name &key_name, const Name &algorithm_name, const void *secret, size_t secret_len, size_t digestbits=0)
 Constructor from key parameters. More...
 
 TSIGKey (const std::string &str)
 Constructor from an input string. More...
 
 TSIGKey (const TSIGKey &source)
 The copy constructor. More...
 
TSIGKeyoperator= (const TSIGKey &source)
 Assignment operator. More...
 
virtual ~TSIGKey ()
 The destructor. More...
 
Getter Methods

These methods never throw an exception.

const NamegetKeyName () const
 Return the key name. More...
 
const NamegetAlgorithmName () const
 Return the algorithm name. More...
 
isc::cryptolink::HashAlgorithm getAlgorithm () const
 Return the hash algorithm name in the form of cryptolink::HashAlgorithm. More...
 
size_t getDigestbits () const
 Return the minimum truncated length. More...
 
size_t getSecretLength () const
 Return the length of the TSIG secret in bytes. More...
 
const void * getSecret () const
 Return the value of the TSIG secret. More...
 

Static Public Member Functions

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.

static const NameHMACMD5_NAME ()
 HMAC-MD5 (RFC2845) More...
 
static const NameHMACMD5_SHORT_NAME ()
 
static const NameHMACSHA1_NAME ()
 HMAC-SHA1 (RFC4635) More...
 
static const NameHMACSHA256_NAME ()
 HMAC-SHA256 (RFC4635) More...
 
static const NameHMACSHA224_NAME ()
 HMAC-SHA256 (RFC4635) More...
 
static const NameHMACSHA384_NAME ()
 HMAC-SHA256 (RFC4635) More...
 
static const NameHMACSHA512_NAME ()
 HMAC-SHA256 (RFC4635) More...
 
static const NameGSSTSIG_NAME ()
 GSS-TSIG (RFC3645) More...
 

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 
)

Constructor from key parameters.

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_nameThe name of the key as a domain name.
algorithm_nameThe hash algorithm used for this key in the form of domain name. For example, it can be TSIGKey::HMACSHA256_NAME() for HMAC-SHA256.
secretPoint to a binary sequence of the shared secret to be used for this key, or NULL if the secret is empty.
secret_lenThe size of the binary data (secret) in bytes.
digestbitsThe number of bits to include in the digest (0 means to include all)

Definition at line 99 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
InvalidParameterexception if the input string is invalid.
Parameters
strThe string to make a TSIGKey from

Definition at line 123 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 192 of file tsigkey.cc.

◆ ~TSIGKey()

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

The destructor.

Definition at line 208 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 223 of file tsigkey.cc.

References isc::dns::TSIGKey::TSIGKeyImpl::algorithm_.

◆ getAlgorithmName()

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

◆ getDigestbits()

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

Return the minimum truncated length.

Definition at line 228 of file tsigkey.cc.

References isc::dns::TSIGKey::TSIGKeyImpl::digestbits_.

Referenced by toText().

◆ getKeyName()

◆ 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 233 of file tsigkey.cc.

References isc::dns::TSIGKey::TSIGKeyImpl::secret_.

Referenced by toText().

◆ getSecretLength()

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

Return the length of the TSIG secret in bytes.

Definition at line 238 of file tsigkey.cc.

References isc::dns::TSIGKey::TSIGKeyImpl::secret_.

Referenced by toText().

◆ GSSTSIG_NAME()

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

GSS-TSIG (RFC3645)

Definition at line 303 of file tsigkey.cc.

◆ HMACMD5_NAME()

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

HMAC-MD5 (RFC2845)

Definition at line 261 of file tsigkey.cc.

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

◆ HMACMD5_SHORT_NAME()

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

Definition at line 267 of file tsigkey.cc.

◆ HMACSHA1_NAME()

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

HMAC-SHA1 (RFC4635)

Definition at line 273 of file tsigkey.cc.

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

◆ HMACSHA224_NAME()

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

HMAC-SHA256 (RFC4635)

Definition at line 285 of file tsigkey.cc.

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

◆ HMACSHA256_NAME()

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

HMAC-SHA256 (RFC4635)

Definition at line 279 of file tsigkey.cc.

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

◆ HMACSHA384_NAME()

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

HMAC-SHA256 (RFC4635)

Definition at line 291 of file tsigkey.cc.

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

◆ HMACSHA512_NAME()

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

HMAC-SHA256 (RFC4635)

Definition at line 297 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 196 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 243 of file tsigkey.cc.

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

+ Here is the call graph for this function:

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