template class Poco::PBKDF2Engine

Overview

This class implementes the Password-Based Key Derivation Function 2, as specified in RFC 2898. More…

#include <PBKDF2Engine.h>

template <class PRF>
class PBKDF2Engine: public Poco::DigestEngine
{
public:
    // enums

    enum
    {
        PRF_DIGEST_SIZE = PRF::DIGEST_SIZE,
    };

    // construction

    PBKDF2Engine(
        const std::string& salt,
        unsigned c = 4096,
        Poco::UInt32 dkLen = PRF_DIGEST_SIZE
        );

    // methods

    virtual
    std::size_t
    digestLength() const;

    virtual
    void
    reset();

    virtual
    const DigestEngine::Digest&
    digest();

protected:
    // methods

    virtual
    void
    updateImpl(
        const void* data,
        std::size_t length
        );

    void
    f(Poco::UInt32 i);
};

Inherited Members

public:
    // typedefs

    typedef std::vector<unsigned char> Digest;

    // methods

    void
    update(
        const void* data,
        std::size_t length
        );

    void
    update(char data);

    void
    update(const std::string& data);

    virtual
    std::size_t
    digestLength() const = 0;

    virtual
    void
    reset() = 0;

    virtual
    const Digest&
    digest() = 0;

    static
    std::string
    digestToHex(const Digest& bytes);

    static
    Digest
    digestFromHex(const std::string& digest);

protected:
    // methods

    virtual
    void
    updateImpl(
        const void* data,
        std::size_t length
        ) = 0;

Detailed Documentation

This class implementes the Password-Based Key Derivation Function 2, as specified in RFC 2898.

The underlying DigestEngine (HMACEngine, etc.), which must accept the passphrase as constructor argument (std::string), must be given as template argument.

PBKDF2 (Password-Based Key Derivation Function 2) is a key derivation function that is part of RSA Laboratories’ Public-Key Cryptography Standards (PKCS) series, specifically PKCS #5 v2.0, also published as Internet Engineering Task Force’s RFC 2898. It replaces an earlier standard, PBKDF1, which could only produce derived keys up to 160 bits long.

PBKDF2 applies a pseudorandom function, such as a cryptographic hash, cipher, or HMAC to the input password or passphrase along with a salt value and repeats the process many times to produce a derived key, which can then be used as a cryptographic key in subsequent operations. The added computational work makes password cracking much more difficult, and is known as key stretching. When the standard was written in 2000, the recommended minimum number of iterations was 1000, but the parameter is intended to be increased over time as CPU speeds increase. Having a salt added to the password reduces the ability to use precomputed hashes (rainbow tables) for attacks, and means that multiple passwords have to be tested individually, not all at once. The standard recommends a salt length of at least 64 bits. [Wikipedia]

The PBKDF2 algorithm is implemented as a DigestEngine. The passphrase is specified by calling update().

Example (WPA2):

PBKDF2Engine<HMACEngine<SHA1Engine> > pbkdf2(ssid, 4096, 256);
pbkdf2.update(passphrase);
DigestEngine::Digest d = pbkdf2.digest();

Methods

virtual
std::size_t
digestLength() const

Returns the length of the digest in bytes.

virtual
void
reset()

Resets the engine so that a new digest can be computed.

virtual
const DigestEngine::Digest&
digest()

Finishes the computation of the digest and returns the message digest.

Resets the engine and can thus only be called once for every digest. The returned reference is valid until the next time digest() is called, or the engine object is destroyed.

virtual
void
updateImpl(
    const void* data,
    std::size_t length
    )

Updates the digest with the given data.

Must be implemented by subclasses.