A simple repository of a set of TSIGKey objects. More...

#include <tsigkey.h>

Classes
struct	FindResult
	A helper structure to represent the search result of `TSIGKeyRing::find()`. More...

struct	TSIGKeyRingImpl

Public Types
enum	Result { SUCCESS = 0, EXIST = 1, NOTFOUND = 2 }
	Result codes of various public methods of `TSIGKeyRing`. More...

Public Member Functions
Result	add (const TSIGKey &key)
	Add a `TSIGKey` to the `TSIGKeyRing`. More...

FindResult	find (const Name &key_name) const
	Find a `TSIGKey` for the given name in the `TSIGKeyRing`. More...

FindResult	find (const Name &key_name, const Name &algorithm_name) const
	Find a `TSIGKey` for the given name in the `TSIGKeyRing`. More...

Result	remove (const Name &key_name)
	Remove a `TSIGKey` for the given name from the `TSIGKeyRing`. More...

unsigned int	size () const
	Return the number of keys stored in the `TSIGKeyRing`. More...

Constructors and Destructor.
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.
	TSIGKeyRing ()
	The default constructor. More...

	~TSIGKeyRing ()
	The destructor. More...

Detailed Description

A simple repository of a set of TSIGKey objects.

This is a "key ring" to maintain TSIG keys (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.

Implementation Note: 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.

Definition at line 246 of file tsigkey.h.

Member Enumeration Documentation

enum isc::dns::TSIGKeyRing::Result

Result codes of various public methods of TSIGKeyRing.

Enumerator
SUCCESS	The operation is successful.
EXIST	A key is already stored in `TSIGKeyRing`.
NOTFOUND	The specified key is not found in `TSIGKeyRing`.

Definition at line 249 of file tsigkey.h.

Constructor & Destructor Documentation

isc::dns::TSIGKeyRing::TSIGKeyRing ( )

The default constructor.

This constructor never throws an exception.

Definition at line 315 of file tsigkey.cc.

isc::dns::TSIGKeyRing::~TSIGKeyRing ( )

The destructor.

Definition at line 318 of file tsigkey.cc.

Member Function Documentation

TSIGKeyRing::Result isc::dns::TSIGKeyRing::add ( const TSIGKey & key )

Add a TSIGKey to the 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.

Parameters

key	A `TSIGKey` to be added.

Returns: SUCCESS If the key is successfully added to the key ring.; EXIST The key ring already stores a key whose name is identical to that of key.

Definition at line 328 of file tsigkey.cc.

References EXIST, isc::dns::TSIGKey::getKeyName(), isc::dns::TSIGKeyRing::TSIGKeyRingImpl::keys, and SUCCESS.

Here is the call graph for this function:

TSIGKeyRing::FindResult isc::dns::TSIGKeyRing::find ( const Name & key_name ) const

Find a TSIGKey for the given name in the TSIGKeyRing.

It searches the internal storage for a TSIGKey whose name is key_name. It returns the result in the form of a FindResult object as follows:

code: SUCCESS if a key is found; otherwise NOTFOUND.
key: A pointer to the found TSIGKey object if one is found; otherwise NULL.

The pointer returned in the 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.

Parameters

key_name The name of the key to be found.

Returns: A FindResult object enclosing the search result (see above).

Definition at line 344 of file tsigkey.cc.

References isc::dns::TSIGKeyRing::TSIGKeyRingImpl::keys, NOTFOUND, and SUCCESS.

Referenced by isc::dns::TSIGContext::TSIGContext().

TSIGKeyRing::FindResult isc::dns::TSIGKeyRing::find	(	const Name &	key_name,
		const Name &	algorithm_name
	)		const

Find a TSIGKey for the given name in the TSIGKeyRing.

It searches the internal storage for a TSIGKey whose name is key_name and that uses the hash algorithm identified by algorithm_name. It returns the result in the form of a FindResult object as follows:

code: SUCCESS if a key is found; otherwise NOTFOUND.
key: A pointer to the found TSIGKey object if one is found; otherwise NULL.

The pointer returned in the 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.

Parameters

key_name	The name of the key to be found.
algorithm_name	The name of the algorithm of the found key.

Returns: A FindResult object enclosing the search result (see above).

Definition at line 354 of file tsigkey.cc.

References isc::dns::TSIGKeyRing::TSIGKeyRingImpl::keys, NOTFOUND, and SUCCESS.

TSIGKeyRing::Result isc::dns::TSIGKeyRing::remove ( const Name & key_name )

Remove a TSIGKey for the given name from the TSIGKeyRing.

This method never throws an exception.

Parameters

key_name The name of the key to be removed.

Returns: SUCCESS If the key is successfully removed from the key ring.; NOTFOUND The key ring does not store the key that matches key_name.

Definition at line 339 of file tsigkey.cc.

References isc::dns::TSIGKeyRing::TSIGKeyRingImpl::keys, NOTFOUND, and SUCCESS.

unsigned int isc::dns::TSIGKeyRing::size ( ) const

Return the number of keys stored in the TSIGKeyRing.

This method never throws an exception.

Definition at line 323 of file tsigkey.cc.

References isc::dns::TSIGKeyRing::TSIGKeyRingImpl::keys.

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

Classes

Public Types

Public Member Functions

Constructors and Destructor.

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation