KeyDerivationFunction

KeyDerivationFunction

Documentation

#include <cryptopp/cryptlib.h>

KeyDerivationFunction is a base class interface that provides a consistent interface for key derivation functions (KDF) and password based key derivation functions (PBKDF). The base class is relatively new and added at Crypto++ 7.0. The interface was added to help support newer KDFs like HKDF and Scrypt. Also see Issue 610, Add KeyDerivationFunction interface and Commit 397f884ce76f.

KeyDerivationFunction provides several class member functions for derived classes and callers. Each class that derives from KeyDerivationFunction will provide the base class DeriveKey shown below, and an overloaded DeriveKey that accepts exactly the parameters of the particular KDF.

A related page is Modular Crypt Format.

DeriveKey

virtual size_t KeyDerivationFunction::DeriveKey(
                   byte *derived, size_t derivedLen,
                   const byte *secret, size_t secretLen,
                   const NameValuePairs &params = g_nullNameValuePairs) const

derived the derived output buffer.

derivedLen the size of the derived buffer, in bytes.

secret the seed input buffer.

secretLen the size of the secret buffer, in bytes.

params additional initialization parameters to configure this object. params is a NameValuePairs object.

DeriveKey returns the number of iterations performed.

DeriveKey throws InvalidDerivedKeyLength if derivedLen is invalid for the scheme.

MinDerivedKeyLength

MinDerivedKeyLength returns the minimum number of bytes which can be derived by the KDF. This is useful to determine if 0 is a valid return value.

MaxDerivedKeyLength

MaxDerivedKeyLength returns the maximum number of bytes which can be derived by the KDF. Some KDs are limited to the size of the underling size of a Block Cipher or Hash.

DeriveKey Overloads

Earlier it was said, each class that derives from KeyDerivationFunction will provide the base class DeriveKey shown below, and an overloaded DeriveKey that accepts exactly the parameters of the particular KDF. Below is an example of PKCS5_PBKDF2_HMAC. Notice the call to the base class DeriveKey calls the overloaded DeriveKey specialized for PKCS5_PBKDF2_HMAC.

template <class T>
size_t PKCS5_PBKDF2_HMAC<T>::DeriveKey(byte *derived, size_t derivedLen,
    const byte *secret, size_t secretLen, const NameValuePairs& params) const
{
    CRYPTOPP_ASSERT(secret /*&& secretLen*/);
    CRYPTOPP_ASSERT(derived && derivedLen);
    CRYPTOPP_ASSERT(derivedLen <= MaxDerivedKeyLength());
 
    byte purpose = (byte)params.GetIntValueWithDefault("Purpose", 0);
    unsigned int iterations = (unsigned int)params.GetIntValueWithDefault("Iterations", 1);
 
    double timeInSeconds = 0.0f;
    (void)params.GetValue("TimeInSeconds", timeInSeconds);
 
    ConstByteArrayParameter salt;
    (void)params.GetValue(Name::Salt(), salt);
 
    return DeriveKey(derived, derivedLen, purpose, secret, secretLen,
               salt.begin(), salt.size(), iterations, timeInSeconds);
}

In the case of PKCS5_PBKDF2_HMAC, the overloaded signature is as follows.

unsigned int DeriveKey (byte *derived, size_t derivedLen,
                 byte purpose,
                 const byte *secret, size_t secretLen,
                 const byte *salt, size_t saltLen,
                 unsigned int iterations,
                 double timeInSeconds=0) const;

Downloads

No downloads.