Kea  2.3.5-git
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

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

◆ 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

◆ TSIGKeyRing()

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

The default constructor.

This constructor never throws an exception.

Definition at line 314 of file tsigkey.cc.

◆ ~TSIGKeyRing()

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

The destructor.

Definition at line 317 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
keyA 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 327 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:

◆ 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_nameThe name of the key to be found.
Returns
A FindResult object enclosing the search result (see above).

Definition at line 343 of file tsigkey.cc.

References isc::dns::TSIGKeyRing::TSIGKeyRingImpl::keys, 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_nameThe name of the key to be found.
algorithm_nameThe name of the algorithm of the found key.
Returns
A FindResult object enclosing the search result (see above).

Definition at line 353 of file tsigkey.cc.

References isc::dns::TSIGKeyRing::TSIGKeyRingImpl::keys, 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_nameThe 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 338 of file tsigkey.cc.

References isc::dns::TSIGKeyRing::TSIGKeyRingImpl::keys, 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 322 of file tsigkey.cc.

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


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