isc::dns::TSIGKeyRing Class Reference

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
	TSIGKeyRing ()
	The default constructor.
	~TSIGKeyRing ()
	The destructor.
Result	add (const TSIGKey &key)
	Add a TSIGKey to the TSIGKeyRing.
FindResult	find (const Name &key_name) const
	Find a TSIGKey for the given name in the TSIGKeyRing.
FindResult	find (const Name &key_name, const Name &algorithm_name) const
	Find a TSIGKey for the given name in the TSIGKeyRing.
Result	remove (const Name &key_name)
	Remove a TSIGKey for the given name from the TSIGKeyRing.
unsigned int	size () const
	Return the number of keys stored in the TSIGKeyRing.

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 245 of file tsigkey.h.

Member Enumeration Documentation

Result

enum isc::dns::TSIGKeyRing::Result

Result codes of various public methods of TSIGKeyRing.

Enumerator
SUCCESS
EXIST
NOTFOUND

Definition at line 248 of file tsigkey.h.

Constructor & Destructor Documentation

TSIGKeyRing()

isc::dns::TSIGKeyRing::TSIGKeyRing

(

)

The default constructor.

This constructor never throws an exception.

Definition at line 257 of file tsigkey.cc.

~TSIGKeyRing()

isc::dns::TSIGKeyRing::~TSIGKeyRing

(

)

The destructor.

Definition at line 260 of file tsigkey.cc.

Member Function Documentation

add()

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 or EXIST if the key ring already stores a key whose name is identical to that of key.

Definition at line 269 of file tsigkey.cc.

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

Here is the call graph for this function:

find() [1/2]

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

References NOTFOUND, and SUCCESS.

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

find() [2/2]

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

References NOTFOUND, and SUCCESS.

remove()

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 or NOTFOUND if the key ring does not store the key that matches key_name.

Definition at line 278 of file tsigkey.cc.

References NOTFOUND, and SUCCESS.

size()

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

---

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

• tsigkey.h
• tsigkey.cc