Kea  2.3.5-git
isc::dns::NSEC3Hash Class Referenceabstract

A calculator of NSEC3 hashes. More...

#include <nsec3hash.h>

Public Member Functions

virtual ~NSEC3Hash ()
 The destructor. More...
 
virtual std::string calculate (const Name &name) const =0
 Calculate the NSEC3 hash (Name variant). More...
 
virtual std::string calculate (const LabelSequence &ls) const =0
 Calculate the NSEC3 hash (LabelSequence variant). More...
 
virtual bool match (const rdata::generic::NSEC3 &nsec3) const =0
 Match given NSEC3 parameters with that of the hash. More...
 
virtual bool match (const rdata::generic::NSEC3PARAM &nsec3param) const =0
 Match given NSEC3PARAM parameters with that of the hash. More...
 

Static Public Member Functions

static NSEC3Hashcreate (const rdata::generic::NSEC3PARAM &param)
 Factory method of NSECHash from NSEC3PARAM RDATA. More...
 
static NSEC3Hashcreate (const rdata::generic::NSEC3 &nsec3)
 Factory method of NSECHash from NSEC3 RDATA. More...
 
static NSEC3Hashcreate (uint8_t algorithm, uint16_t iterations, const uint8_t *salt_data, size_t salt_length)
 Factory method of NSECHash from args. More...
 

Protected Member Functions

 NSEC3Hash ()
 The default constructor. More...
 

Detailed Description

A calculator of NSEC3 hashes.

This is an abstract base class that defines a simple interface to calculating NSEC3 hash values as defined in RFC5155.

(Derived classes of) this class is designed to be "stateless" in that it basically doesn't hold mutable state once constructed, and hash calculation solely depends on the parameters given on construction and input to the calculate() method. In that sense this could be a single free function rather than a class, but we decided to provide the functionality as a class for two reasons: NSEC3 hash calculations would often take place more than one time in a single query or validation process, so it would be more efficient if we could hold some internal resources used for the calculation and reuse it over multiple calls to calculate() (a concrete implementation in this library actually does this); Second, we may want to customize the hash calculation logic for testing purposes or for other future extensions. For example, we may want to use a fake calculator for tests that returns pre-defined hash values (so a slight change to the test input wouldn't affect the test result). Using classes from this base would make it possible more transparently to the application.

A specific derived class instance must be created by the factory method, create().

There can be several ways to extend this class in future. Those include:

  • Allow customizing the factory method so the application change the behavior dynamically.
  • Allow to construct the class from a tuple of parameters, that is, integers for algorithm, iterations and flags, and opaque salt data. For example, we might want to use that version for validators.
  • Allow producing hash value as binary data
  • Allow updating NSEC3 parameters of a class object so we can still reuse the internal resources for different sets of parameters.

Definition at line 74 of file nsec3hash.h.

Constructor & Destructor Documentation

◆ NSEC3Hash()

isc::dns::NSEC3Hash::NSEC3Hash ( )
inlineprotected

The default constructor.

This is defined as protected to prevent this class from being directly instantiated even if the class definition is modified (accidentally or intentionally) to have no pure virtual methods.

Definition at line 81 of file nsec3hash.h.

◆ ~NSEC3Hash()

virtual isc::dns::NSEC3Hash::~NSEC3Hash ( )
inlinevirtual

The destructor.

Definition at line 123 of file nsec3hash.h.

Member Function Documentation

◆ calculate() [1/2]

virtual std::string isc::dns::NSEC3Hash::calculate ( const Name name) const
pure virtual

Calculate the NSEC3 hash (Name variant).

This method calculates the NSEC3 hash value for the given name with the hash parameters (algorithm, iterations and salt) given at construction, and returns the value as a base32hex-encoded string (without containing any white spaces). All US-ASCII letters in the string will be lower cased.

Parameters
nameThe domain name for which the hash value is to be calculated.
Returns
Base32hex-encoded string of the hash value.

◆ calculate() [2/2]

virtual std::string isc::dns::NSEC3Hash::calculate ( const LabelSequence ls) const
pure virtual

Calculate the NSEC3 hash (LabelSequence variant).

This method calculates the NSEC3 hash value for the given absolute LabelSequence ls with the hash parameters (algorithm, iterations and salt) given at construction, and returns the value as a base32hex-encoded string (without containing any white spaces). All US-ASCII letters in the string will be lower cased.

Parameters
lsThe absolute label sequence for which the hash value is to be calculated.
Returns
Base32hex-encoded string of the hash value.

◆ create() [1/3]

NSEC3Hash * isc::dns::NSEC3Hash::create ( const rdata::generic::NSEC3PARAM param)
static

Factory method of NSECHash from NSEC3PARAM RDATA.

The hash algorithm given via param must be known to the implementation. Otherwise UnknownNSEC3HashAlgorithm exception will be thrown.

This method creates an NSEC3Hash object using new. The caller is responsible for releasing it with delete that is compatible to the one used in this library. In practice, the application would generally need to store the returned pointer in some form of smart pointer; otherwise the resulting code will be quite fragile against exceptions (and in this case the application doesn't have to worry about explicit delete).

Exceptions
UnknownNSEC3HashAlgorithmThe specified algorithm in param is unknown.
std::bad_allocInternal resource allocation failure.
Parameters
paramNSEC3 parameters used for subsequent calculation.
Returns
A pointer to a concrete derived object of NSEC3Hash.

Definition at line 221 of file nsec3hash.cc.

◆ create() [2/3]

NSEC3Hash * isc::dns::NSEC3Hash::create ( const rdata::generic::NSEC3 nsec3)
static

Factory method of NSECHash from NSEC3 RDATA.

This is similar to the other version, but extracts the parameters for hash calculation from an NSEC3 RDATA object.

Definition at line 226 of file nsec3hash.cc.

◆ create() [3/3]

NSEC3Hash * isc::dns::NSEC3Hash::create ( uint8_t  algorithm,
uint16_t  iterations,
const uint8_t *  salt_data,
size_t  salt_length 
)
static

Factory method of NSECHash from args.

Parameters
algorithmthe NSEC3 algorithm to use; currently only 1 (SHA-1) is supported
iterationsthe number of iterations
salt_datathe salt data as a byte array
salt_lengththe length of the salt data

Definition at line 231 of file nsec3hash.cc.

◆ match() [1/2]

virtual bool isc::dns::NSEC3Hash::match ( const rdata::generic::NSEC3 nsec3) const
pure virtual

Match given NSEC3 parameters with that of the hash.

This method compares NSEC3 parameters used for hash calculation in the object with those in the given NSEC3 RDATA, and return true iff they completely match. In the current implementation only the algorithm, iterations and salt are compared; the flags are ignored (as they don't affect hash calculation per RFC5155).

Exceptions
None
Parameters
nsec3An NSEC3 RDATA object whose hash parameters are to be matched
Returns
true If the given parameters match the local ones; false otherwise.

◆ match() [2/2]

virtual bool isc::dns::NSEC3Hash::match ( const rdata::generic::NSEC3PARAM nsec3param) const
pure virtual

Match given NSEC3PARAM parameters with that of the hash.

This is similar to the other version, but extracts the parameters to compare from an NSEC3PARAM RDATA object.


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