PKCS12 PBKDF

PKCS12_PBKDF

Documentation

#include <cryptopp/pwdbased.h>

PKCS12_PBKDF is an early key derivation function (KDF) specified by PKCS #12. The function takes a secret seed, usage and iteration count and outputs key material.

PKCS12_PBKDF derives from KeyDerivationFunction interface. PKCS12_PBKDF provides two DeriveKey member functions. The first member function is required by KeyDerivationFunction and accepts a NameValuePairs object to pass arbitrary parameters. The second DeriveKey overload provides a specialized DeriveKey with parameters tuned for PKCS12_PBKDF.

PKCS12_PBKDF is an older standard. Early KDFs from the bygone era include P1363_KDF2, PKCS12_PBKDF, PKCS5_PBKDF1 and PKCS5_PBKDF2_HMAC. New applications should consider using a modern KDF, like HKDF. HKDF is state of the art extract-then-expand derivation function with provable security properties.

Constructor

PKCS12_PBKDF provides a default constructor.

DeriveKey

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

derived is the buffer to receive the derived key. derivedLen is the size of the buffer, in bytes.

purpose is a purpose byte. PKCS12_PBKDF uses the purpose octet.

secret is private information to use during derivation. secretLen is the size of the buffer, in bytes.

salt is possibly public information to use during derivation. saltLen is the size of the buffer, in bytes.

iterations is an iteration count.

timeInSeconds is the maximum amount of time to iterate the DeriveKey function.

DeriveKey returns the number of iteration.

salt and info are used to help distinguish one instance or run of the algorithm from another. The parameters can be NULL.

If timeInSeconds > 0.0 then DeriveKey will run for the specified amount of time. If timeInSeconds is 0.0 then DeriveKey will run for the specified number of iterations.

KeyDerivationFunction

The base class interface KeyDerivationFunction member function DeriveKey calls the overloaded DeriveKey. The following is from pwdbased.h.

template <class T>
size_t PKCS12_PBKDF<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);
 
    // NULL or 0 length salt OK
    ConstByteArrayParameter salt;
    (void)params.GetValue(Name::Salt(), salt);
 
    return DeriveKey(derived, derivedLen, purpose, secret, secretLen,
               salt.begin(), salt.size(), iterations, timeInSeconds);
}

Sample Program

The sample program below demonstrates a PKCS12_PBKDF with SHA256.

$ cat test.cxx
#include <iostream>
#include <string>

#include "cryptlib.h"
#include "pwdbased.h"
#include "sha.h"
#include "hex.h"

int main(int argc, char* argv[])
{
    using namespace CryptoPP;

    byte password[] ="password";
    size_t plen = strlen((const char*)password);

    byte salt[] = "salt";
    size_t slen = strlen((const char*)salt);

    byte derived[SHA256::DIGESTSIZE];

    PKCS12_PBKDF<SHA256> pbkdf;
    byte purpose = 0;

    pbkdf.DeriveKey(derived, sizeof(derived), purpose, password, plen, salt, slen, 1024, 0.0f);

    std::string result;
    HexEncoder encoder(new StringSink(result));

    encoder.Put(derived, sizeof(derived));
    encoder.MessageEnd();

    std::cout << "Derived: " << result << std::endl;

    return 0;
}

Running the program results in the following.

$ ./test.exe
Derived: 46FB1E99AA495B548F67302782AFEF4711497437F084C66CB21B37AEB8206EF1

You can swap-in any hash class that provides a blocksize. The code below uses BLAKE2b as the message digest. The BLAKE2b sample below requires Commit 758939ab2e1b.

$ cat test.cxx
#include <iostream>
#include <string>

#include "cryptlib.h"
#include "pwdbased.h"
#include "blake2.h"
#include "hex.h"

int main(int argc, char* argv[])
{
    using namespace CryptoPP;

    byte password[] ="password";
    size_t plen = strlen((const char*)password);

    byte salt[] = "salt";
    size_t slen = strlen((const char*)salt);

    byte derived[BLAKE2b::DIGESTSIZE];

    PKCS12_PBKDF<BLAKE2b> pbkdf;
    byte purpose = 0;

    pbkdf.DeriveKey(derived, sizeof(derived), purpose, password, plen, salt, slen, 1024, 0.0f);

    std::string result;
    HexEncoder encoder(new StringSink(result));

    encoder.Put(derived, sizeof(derived));
    encoder.MessageEnd();

    std::cout << "Derived: " << result << std::endl;

    return 0;
}

Running the program results in the following.

$ ./test.exe
Derived: D5B45659CB2A9D967B605BB95C5C0DC1EE2454F76DD6592208A793BB6DC8CAB7E53892F
4F9FAF5BBE743AE888FC8C87369AFC9FBE64E656D666408E30CF11439

The sample program below demonstrates a PKCS12_PBKDF with SHA256, and uses the derived material to key a block cipher. Notice two different labels are used. First, the label HKDF key derivation to derive the key; and second, the label HKDF iv derivation to derive the initialization vector.

$ cat test.cxx
#include <iostream>
#include <string>

#include "cryptlib.h"
#include "pwdbased.h"
#include "sha.h"
#include "files.h"
#include "aes.h"
#include "modes.h"
#include "hex.h"

int main(int argc, char* argv[])
{
    using namespace CryptoPP;

    byte password[] ="password";
    size_t plen = strlen((const char*)password);

    byte info1[] = "PKCS12_PBKDF key derivation";
    size_t ilen1 = strlen((const char*)info1);

    byte info2[] = "PKCS12_PBKDF iv derivation";
    size_t ilen2 = strlen((const char*)info2);

    byte key[AES::DEFAULT_KEYLENGTH];
    byte iv[AES::BLOCKSIZE];

    PKCS12_PBKDF<SHA256> pbkdf;
    byte purpose = 0;

    pbkdf.DeriveKey(key, sizeof(key), purpose, password, plen, info1, ilen1, 1024, 0.0f);
    pbkdf.DeriveKey(iv, sizeof(iv), purpose, password, plen, info2, ilen2, 1024, 0.0f);

    std::cout << "Key: ";
    StringSource(key, sizeof(key), true, new HexEncoder(new FileSink(std::cout)));
    std::cout << std::endl;

    std::cout << "IV: ";
    StringSource(iv, sizeof(iv), true, new HexEncoder(new FileSink(std::cout)));
    std::cout << std::endl;

    CBC_Mode<AES>::Encryption enc;
    enc.SetKeyWithIV(key, sizeof(key), iv, sizeof(iv));

    // Use AES/CBC encryptor

    return 0;
}

Running the program results in the following.

$ ./test.exe 
Key: 22571DBE3FC26268CE4F80D7A13F762A
IV: AFC15EECE0DBEEF3A596281E14DD954B

Downloads

No downloads.