diff options
Diffstat (limited to 'src/lib/dns/tsigkey.h')
| -rw-r--r-- | src/lib/dns/tsigkey.h | 391 |
1 files changed, 391 insertions, 0 deletions
diff --git a/src/lib/dns/tsigkey.h b/src/lib/dns/tsigkey.h new file mode 100644 index 0000000..ead33e1 --- /dev/null +++ b/src/lib/dns/tsigkey.h @@ -0,0 +1,391 @@ +// Copyright (C) 2010-2021 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 http://mozilla.org/MPL/2.0/. + +#ifndef TSIGKEY_H +#define TSIGKEY_H 1 + +#include <cryptolink/cryptolink.h> + +namespace isc { +namespace dns { + +class Name; + +/// \brief 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 +/// +/// <b>Implementation Notes</b> +/// +/// 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 \c Name object to specify the +/// algorithm. +/// On one hand, this may be counter intuitive. +/// An API user would rather specify "hmac-md5" instead of +/// <code>Name("hmac-md5.sig-alg.reg.int")</code>. +/// 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. +class TSIGKey { +public: + /// + /// \name Constructors, Assignment Operator and Destructor. + /// + //@{ + /// \brief Constructor from key parameters + /// + /// \c algorithm_name should generally be a known algorithm to this + /// implementation, which are defined via the + /// <code>static const</code> member functions. + /// + /// Other names are still accepted as long as the secret is empty + /// (\c secret is \c NULL and \c 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 \c 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 \c InvalidParameter will be thrown. + /// + /// \c secret and \c secret_len must be consistent in that the latter + /// is 0 if and only if the former is \c NULL; + /// otherwise an exception of type \c InvalidParameter will be thrown. + /// + /// \c 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. + /// + /// \param key_name The name of the key as a domain name. + /// \param algorithm_name The hash algorithm used for this key in the + /// form of domain name. For example, it can be + /// \c TSIGKey::HMACSHA256_NAME() for HMAC-SHA256. + /// \param secret Point to a binary sequence of the shared secret to be + /// used for this key, or \c NULL if the secret is empty. + /// \param secret_len The size of the binary %data (\c secret) in bytes. + /// \param digestbits The number of bits to include in the digest + /// (0 means to include all) + TSIGKey(const Name& key_name, const Name& algorithm_name, + const void* secret, size_t secret_len, size_t digestbits = 0); + + /// \brief 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. + /// + /// \exception InvalidParameter exception if the input string is + /// invalid. + /// + /// \param str The string to make a TSIGKey from + explicit TSIGKey(const std::string& str); + + /// \brief 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. + TSIGKey(const TSIGKey& source); + + /// \brief 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. + TSIGKey& operator=(const TSIGKey& source); + + /// The destructor. + virtual ~TSIGKey(); + //@} + + /// + /// \name Getter Methods + /// + /// These methods never throw an exception. + //@{ + /// Return the key name. + const Name& getKeyName() const; + + /// Return the algorithm name. + const Name& getAlgorithmName() const; + + /// Return the hash algorithm name in the form of cryptolink::HashAlgorithm + isc::cryptolink::HashAlgorithm getAlgorithm() const; + + /// Return the minimum truncated length. + size_t getDigestbits() const; + + /// Return the length of the TSIG secret in bytes. + size_t getSecretLength() 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 \c getSecretLength(). + /// + /// The memory region is only valid while the corresponding \c TSIGKey + /// object is valid. The caller must hold the \c TSIGKey object while + /// it needs to refer to the region or it must make a local copy of the + /// region. + const void* getSecret() const; + //@} + + /// \brief 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. + /// + /// \return The string representation of the given TSIGKey. + std::string toText() const; + + /// + /// \name 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 Name& HMACMD5_NAME(); ///< HMAC-MD5 (RFC2845) + static const Name& HMACMD5_SHORT_NAME(); + static const Name& HMACSHA1_NAME(); ///< HMAC-SHA1 (RFC4635) + static const Name& HMACSHA256_NAME(); ///< HMAC-SHA256 (RFC4635) + static const Name& HMACSHA224_NAME(); ///< HMAC-SHA256 (RFC4635) + static const Name& HMACSHA384_NAME(); ///< HMAC-SHA256 (RFC4635) + static const Name& HMACSHA512_NAME(); ///< HMAC-SHA256 (RFC4635) + static const Name& GSSTSIG_NAME(); ///< GSS-TSIG (RFC3645) + //@} + +private: + struct TSIGKeyImpl; + const TSIGKeyImpl* impl_; +}; + +/// \brief A simple repository of a set of \c TSIGKey objects. +/// +/// This is a "key ring" to maintain TSIG keys (\c TSIGKey objects) and +/// provides trivial operations such as add, remove, and find. +/// +/// The keys are identified by their key names. +/// So, for example, two or more keys of the same key name but of different +/// algorithms are considered to be the same, and cannot be stored in the +/// key ring at the same time. +/// +/// <b>Implementation Note:</b> +/// For simplicity the initial implementation requests the application make +/// a copy of keys stored in the key ring if it needs to use the keys for +/// a long period (during which some of the keys may be removed). +/// This is based on the observations that a single server will not hold +/// a huge number of keys nor use keys in many different contexts (such as +/// in different DNS transactions). +/// If this assumption does not hold and memory consumption becomes an issue +/// we may have to revisit the design. +class TSIGKeyRing { +public: + /// Result codes of various public methods of \c TSIGKeyRing + enum Result { + SUCCESS = 0, ///< The operation is successful. + EXIST = 1, ///< A key is already stored in \c TSIGKeyRing. + NOTFOUND = 2 ///< The specified key is not found in \c TSIGKeyRing. + }; + + /// \brief A helper structure to represent the search result of + /// <code>TSIGKeyRing::find()</code>. + /// + /// This is a straightforward pair of the result code and a pointer + /// to the found key to represent the result of \c find(). + /// We use this in order to avoid overloading the return value for both + /// the result code ("success" or "not found") and the found object, + /// i.e., avoid using \c NULL to mean "not found", etc. + /// + /// This is a simple value class with no internal state, so for + /// convenience we allow the applications to refer to the members + /// directly. + /// + /// See the description of \c find() for the semantics of the member + /// variables. + struct FindResult { + FindResult(Result param_code, const TSIGKey* param_key) : + code(param_code), key(param_key) + {} + const Result code; + const TSIGKey* const key; + }; + + /// + /// \name Constructors and Destructor. + /// + /// \b Note: + /// The copy constructor and the assignment operator are + /// intentionally defined as private, making this class non copyable. + /// There is no technical reason why this class cannot be copied, + /// but since the key ring can potentially have a large number of keys, + /// a naive copy operation may cause unexpected overhead. + /// It's generally expected for an application to share the same + /// instance of key ring and share it throughout the program via + /// references, so we prevent the copy operation explicitly to avoid + /// unexpected copy operations. + //@{ +private: + TSIGKeyRing(const TSIGKeyRing& source); + TSIGKeyRing& operator=(const TSIGKeyRing& source); +public: + /// \brief The default constructor. + /// + /// This constructor never throws an exception. + TSIGKeyRing(); + + /// The destructor. + ~TSIGKeyRing(); + //@} + + /// Return the number of keys stored in the \c TSIGKeyRing. + /// + /// This method never throws an exception. + unsigned int size() const; + + /// Add a \c TSIGKey to the \c TSIGKeyRing. + /// + /// This method will create a local copy of the given key, so the caller + /// does not have to keep owning it. + /// + /// If internal resource allocation fails, a corresponding standard + /// exception will be thrown. + /// This method never throws an exception otherwise. + /// + /// \param key A \c TSIGKey to be added. + /// \return \c SUCCESS If the key is successfully added to the key ring. + /// \return \c EXIST The key ring already stores a key whose name is + /// identical to that of \c key. + Result add(const TSIGKey& key); + + /// Remove a \c TSIGKey for the given name from the \c TSIGKeyRing. + /// + /// This method never throws an exception. + /// + /// \param key_name The name of the key to be removed. + /// \return \c SUCCESS If the key is successfully removed from the key + /// ring. + /// \return \c NOTFOUND The key ring does not store the key that matches + /// \c key_name. + Result remove(const Name& key_name); + + /// Find a \c TSIGKey for the given name in the \c TSIGKeyRing. + /// + /// It searches the internal storage for a \c TSIGKey whose name is + /// \c key_name. + /// It returns the result in the form of a \c FindResult + /// object as follows: + /// - \c code: \c SUCCESS if a key is found; otherwise \c NOTFOUND. + /// - \c key: A pointer to the found \c TSIGKey object if one is found; + /// otherwise \c NULL. + /// + /// The pointer returned in the \c FindResult object is only valid until + /// the corresponding key is removed from the key ring. + /// The caller must ensure that the key is held in the key ring while + /// it needs to refer to it, or it must make a local copy of the key. + /// + /// This method never throws an exception. + /// + /// \param key_name The name of the key to be found. + /// \return A \c FindResult object enclosing the search result (see above). + FindResult find(const Name& key_name) const; + + /// Find a \c TSIGKey for the given name in the \c TSIGKeyRing. + /// + /// It searches the internal storage for a \c TSIGKey whose name is + /// \c key_name and that uses the hash algorithm identified by + /// \c algorithm_name. + /// It returns the result in the form of a \c FindResult + /// object as follows: + /// - \c code: \c SUCCESS if a key is found; otherwise \c NOTFOUND. + /// - \c key: A pointer to the found \c TSIGKey object if one is found; + /// otherwise \c NULL. + /// + /// The pointer returned in the \c FindResult object is only valid until + /// the corresponding key is removed from the key ring. + /// The caller must ensure that the key is held in the key ring while + /// it needs to refer to it, or it must make a local copy of the key. + /// + /// This method never throws an exception. + /// + /// \param key_name The name of the key to be found. + /// \param algorithm_name The name of the algorithm of the found key. + /// \return A \c FindResult object enclosing the search result (see above). + FindResult find(const Name& key_name, const Name& algorithm_name) const; + +private: + struct TSIGKeyRingImpl; + TSIGKeyRingImpl* impl_; +}; +} +} + +#endif // TSIGKEY_H + +// Local Variables: +// mode: c++ +// End: |