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 NSEC3Hash *	create (const rdata::generic::NSEC3PARAM &param)
	Factory method of NSECHash from NSEC3PARAM RDATA. More...

static NSEC3Hash *	create (const rdata::generic::NSEC3 &nsec3)
	Factory method of NSECHash from NSEC3 RDATA. More...

static NSEC3Hash *	create (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

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.

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

inlinevirtual

The destructor.

Definition at line 123 of file nsec3hash.h.

Member Function Documentation

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

name	The domain name for which the hash value is to be calculated.

Returns: Base32hex-encoded string of the hash value.

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

ls	The absolute label sequence for which the hash value is to be calculated.

Returns: Base32hex-encoded string of the hash value.

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

UnknownNSEC3HashAlgorithm	The specified algorithm in `param` is unknown.
std::bad_alloc	Internal resource allocation failure.

Parameters

param NSEC3 parameters used for subsequent calculation.

Returns: A pointer to a concrete derived object of NSEC3Hash.

Definition at line 221 of file nsec3hash.cc.

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.

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

algorithm	the NSEC3 algorithm to use; currently only 1 (SHA-1) is supported
iterations	the number of iterations
salt_data	the salt data as a byte array
salt_length	the length of the salt data

Definition at line 231 of file nsec3hash.cc.

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

nsec3 An NSEC3 RDATA object whose hash parameters are to be matched

Returns: true If the given parameters match the local ones; false otherwise.

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:

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation