Botan 2.19.3
Crypto and TLS for C&
Public Member Functions | Static Public Member Functions | List of all members
Botan::PBKDF Class Referenceabstract

#include <pbkdf.h>

Inheritance diagram for Botan::PBKDF:
Botan::OpenPGP_S2K Botan::PKCS5_PBKDF1 Botan::PKCS5_PBKDF2

Public Member Functions

virtual PBKDFclone () const =0
 
template<typename Alloc >
OctetString derive_key (size_t out_len, const std::string &passphrase, const std::vector< uint8_t, Alloc > &salt, size_t iterations) const
 
template<typename Alloc >
OctetString derive_key (size_t out_len, const std::string &passphrase, const std::vector< uint8_t, Alloc > &salt, std::chrono::milliseconds msec, size_t &iterations) const
 
OctetString derive_key (size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
 
OctetString derive_key (size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
 
virtual std::string name () const =0
 
virtual size_t pbkdf (uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec) const =0
 
secure_vector< uint8_t > pbkdf_iterations (size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
 
void pbkdf_iterations (uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
 
secure_vector< uint8_t > pbkdf_timed (size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
 
void pbkdf_timed (uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
 
virtual ~PBKDF ()=default
 

Static Public Member Functions

static std::unique_ptr< PBKDFcreate (const std::string &algo_spec, const std::string &provider="")
 
static std::unique_ptr< PBKDFcreate_or_throw (const std::string &algo_spec, const std::string &provider="")
 
static std::vector< std::string > providers (const std::string &algo_spec)
 

Detailed Description

Base class for PBKDF (password based key derivation function) implementations. Converts a password into a key using a salt and iterated hashing to make brute force attacks harder.

Starting in 2.8 this functionality is also offered by PasswordHash. The PBKDF interface may be removed in a future release.

Definition at line 24 of file pbkdf.h.

Constructor & Destructor Documentation

◆ ~PBKDF()

virtual Botan::PBKDF::~PBKDF ( )
virtualdefault

Member Function Documentation

◆ clone()

virtual PBKDF * Botan::PBKDF::clone ( ) const
pure virtual
Returns
new instance of this same algorithm

Implemented in Botan::PKCS5_PBKDF1, Botan::PKCS5_PBKDF2, and Botan::OpenPGP_S2K.

◆ create()

std::unique_ptr< PBKDF > Botan::PBKDF::create ( const std::string &  algo_spec,
const std::string &  provider = "" 
)
static

Create an instance based on a name If provider is empty then best available is chosen.

Parameters
algo_specalgorithm name
providerprovider implementation to choose
Returns
a null pointer if the algo/provider combination cannot be found

Definition at line 26 of file pbkdf.cpp.

28 {
29 const SCAN_Name req(algo_spec);
30
31#if defined(BOTAN_HAS_PBKDF2)
32 if(req.algo_name() == "PBKDF2")
33 {
34 if(provider.empty() || provider == "base")
35 {
36 if(auto mac = MessageAuthenticationCode::create(req.arg(0)))
37 return std::unique_ptr<PBKDF>(new PKCS5_PBKDF2(mac.release()));
38
39 if(auto mac = MessageAuthenticationCode::create("HMAC(" + req.arg(0) + ")"))
40 return std::unique_ptr<PBKDF>(new PKCS5_PBKDF2(mac.release()));
41 }
42
43 return nullptr;
44 }
45#endif
46
47#if defined(BOTAN_HAS_PBKDF1)
48 if(req.algo_name() == "PBKDF1" && req.arg_count() == 1)
49 {
50 if(auto hash = HashFunction::create(req.arg(0)))
51 return std::unique_ptr<PBKDF>(new PKCS5_PBKDF1(hash.release()));
52
53 }
54#endif
55
56#if defined(BOTAN_HAS_PGP_S2K)
57 if(req.algo_name() == "OpenPGP-S2K" && req.arg_count() == 1)
58 {
59 if(auto hash = HashFunction::create(req.arg(0)))
60 return std::unique_ptr<PBKDF>(new OpenPGP_S2K(hash.release()));
61 }
62#endif
63
64 BOTAN_UNUSED(req);
65 BOTAN_UNUSED(provider);
66
67 return nullptr;
68 }
#define BOTAN_UNUSED(...)
Definition assert.h:142
static std::unique_ptr< HashFunction > create(const std::string &algo_spec, const std::string &provider="")
Definition hash.cpp:102
static std::unique_ptr< MessageAuthenticationCode > create(const std::string &algo_spec, const std::string &provider="")
Definition mac.cpp:46
MechanismType hash

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg(), Botan::SCAN_Name::arg_count(), BOTAN_UNUSED, Botan::HashFunction::create(), Botan::MessageAuthenticationCode::create(), and hash.

Referenced by create_or_throw().

◆ create_or_throw()

std::unique_ptr< PBKDF > Botan::PBKDF::create_or_throw ( const std::string &  algo_spec,
const std::string &  provider = "" 
)
static

Create an instance based on a name, or throw if the algo/provider combination cannot be found. If provider is empty then best available is chosen.

Definition at line 72 of file pbkdf.cpp.

74 {
75 if(auto pbkdf = PBKDF::create(algo, provider))
76 {
77 return pbkdf;
78 }
79 throw Lookup_Error("PBKDF", algo, provider);
80 }
virtual size_t pbkdf(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec) const =0
static std::unique_ptr< PBKDF > create(const std::string &algo_spec, const std::string &provider="")
Definition pbkdf.cpp:26

References create(), and pbkdf().

Referenced by Botan::CryptoBox::decrypt_bin(), Botan::CryptoBox::encrypt(), and Botan::get_pbkdf().

◆ derive_key() [1/4]

template<typename Alloc >
OctetString Botan::PBKDF::derive_key ( size_t  out_len,
const std::string &  passphrase,
const std::vector< uint8_t, Alloc > &  salt,
size_t  iterations 
) const
inline

Derive a key from a passphrase

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
iterationsthe number of iterations to use (use 10K or more)

Definition at line 176 of file pbkdf.h.

180 {
181 return pbkdf_iterations(out_len, passphrase, salt.data(), salt.size(), iterations);
182 }
void pbkdf_iterations(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
Definition pbkdf.cpp:96

◆ derive_key() [2/4]

template<typename Alloc >
OctetString Botan::PBKDF::derive_key ( size_t  out_len,
const std::string &  passphrase,
const std::vector< uint8_t, Alloc > &  salt,
std::chrono::milliseconds  msec,
size_t &  iterations 
) const
inline

Derive a key from a passphrase using a certain amount of time

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
msecis how long to run the PBKDF
iterationsis set to the number of iterations used

Definition at line 211 of file pbkdf.h.

216 {
217 return pbkdf_timed(out_len, passphrase, salt.data(), salt.size(), msec, iterations);
218 }
void pbkdf_timed(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
Definition pbkdf.cpp:87

◆ derive_key() [3/4]

OctetString Botan::PBKDF::derive_key ( size_t  out_len,
const std::string &  passphrase,
const uint8_t  salt[],
size_t  salt_len,
size_t  iterations 
) const
inline

Derive a key from a passphrase

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
iterationsthe number of iterations to use (use 10K or more)

Definition at line 160 of file pbkdf.h.

164 {
165 return pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations);
166 }
size_t salt_len
Definition x509_obj.cpp:25

References salt_len.

Referenced by Botan::check_passhash9(), and Botan::generate_passhash9().

◆ derive_key() [4/4]

OctetString Botan::PBKDF::derive_key ( size_t  out_len,
const std::string &  passphrase,
const uint8_t  salt[],
size_t  salt_len,
std::chrono::milliseconds  msec,
size_t &  iterations 
) const
inline

Derive a key from a passphrase

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
msecis how long to run the PBKDF
iterationsis set to the number of iterations used

Definition at line 193 of file pbkdf.h.

198 {
199 return pbkdf_timed(out_len, passphrase, salt, salt_len, msec, iterations);
200 }

References salt_len.

◆ name()

virtual std::string Botan::PBKDF::name ( ) const
pure virtual
Returns
name of this PBKDF

Implemented in Botan::PKCS5_PBKDF1, Botan::PKCS5_PBKDF2, and Botan::OpenPGP_S2K.

Referenced by pbkdf_iterations().

◆ pbkdf()

virtual size_t Botan::PBKDF::pbkdf ( uint8_t  out[],
size_t  out_len,
const std::string &  passphrase,
const uint8_t  salt[],
size_t  salt_len,
size_t  iterations,
std::chrono::milliseconds  msec 
) const
pure virtual

Derive a key from a passphrase for a number of iterations specified by either iterations or if iterations == 0 then running until msec time has elapsed.

Parameters
outbuffer to store the derived key, must be of out_len bytes
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
iterationsthe number of iterations to use (use 10K or more)
msecif iterations is zero, then instead the PBKDF is run until msec milliseconds has passed.
Returns
the number of iterations performed

Implemented in Botan::PKCS5_PBKDF1, Botan::PKCS5_PBKDF2, and Botan::OpenPGP_S2K.

Referenced by create_or_throw(), pbkdf_iterations(), and pbkdf_timed().

◆ pbkdf_iterations() [1/2]

secure_vector< uint8_t > Botan::PBKDF::pbkdf_iterations ( size_t  out_len,
const std::string &  passphrase,
const uint8_t  salt[],
size_t  salt_len,
size_t  iterations 
) const

Derive a key from a passphrase for a number of iterations.

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
iterationsthe number of iterations to use (use 10K or more)
Returns
the derived key

Definition at line 110 of file pbkdf.cpp.

114 {
115 secure_vector<uint8_t> out(out_len);
116 pbkdf_iterations(out.data(), out_len, passphrase, salt, salt_len, iterations);
117 return out;
118 }

References pbkdf_iterations(), and salt_len.

◆ pbkdf_iterations() [2/2]

void Botan::PBKDF::pbkdf_iterations ( uint8_t  out[],
size_t  out_len,
const std::string &  passphrase,
const uint8_t  salt[],
size_t  salt_len,
size_t  iterations 
) const

Derive a key from a passphrase for a number of iterations.

Parameters
outbuffer to store the derived key, must be of out_len bytes
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
iterationsthe number of iterations to use (use 10K or more)

Definition at line 96 of file pbkdf.cpp.

100 {
101 if(iterations == 0)
102 throw Invalid_Argument(name() + ": Invalid iteration count");
103
104 const size_t iterations_run = pbkdf(out, out_len, passphrase,
105 salt, salt_len, iterations,
106 std::chrono::milliseconds(0));
107 BOTAN_ASSERT_EQUAL(iterations, iterations_run, "Expected PBKDF iterations");
108 }
#define BOTAN_ASSERT_EQUAL(expr1, expr2, assertion_made)
Definition assert.h:81
virtual std::string name() const =0

References BOTAN_ASSERT_EQUAL, name(), pbkdf(), and salt_len.

Referenced by pbkdf_iterations().

◆ pbkdf_timed() [1/2]

secure_vector< uint8_t > Botan::PBKDF::pbkdf_timed ( size_t  out_len,
const std::string &  passphrase,
const uint8_t  salt[],
size_t  salt_len,
std::chrono::milliseconds  msec,
size_t &  iterations 
) const

Derive a key from a passphrase, running until msec time has elapsed.

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
msecif iterations is zero, then instead the PBKDF is run until msec milliseconds has passed.
iterationsset to the number iterations executed
Returns
the derived key

Definition at line 120 of file pbkdf.cpp.

125 {
126 secure_vector<uint8_t> out(out_len);
127 pbkdf_timed(out.data(), out_len, passphrase, salt, salt_len, msec, iterations);
128 return out;
129 }

References pbkdf_timed(), and salt_len.

◆ pbkdf_timed() [2/2]

void Botan::PBKDF::pbkdf_timed ( uint8_t  out[],
size_t  out_len,
const std::string &  passphrase,
const uint8_t  salt[],
size_t  salt_len,
std::chrono::milliseconds  msec,
size_t &  iterations 
) const

Derive a key from a passphrase, running until msec time has elapsed.

Parameters
outbuffer to store the derived key, must be of out_len bytes
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
msecif iterations is zero, then instead the PBKDF is run until msec milliseconds has passed.
iterationsset to the number iterations executed

Definition at line 87 of file pbkdf.cpp.

92 {
93 iterations = pbkdf(out, out_len, passphrase, salt, salt_len, 0, msec);
94 }

References pbkdf(), and salt_len.

Referenced by pbkdf_timed().

◆ providers()

std::vector< std::string > Botan::PBKDF::providers ( const std::string &  algo_spec)
static
Returns
list of available providers for this algorithm, empty if not available

Definition at line 82 of file pbkdf.cpp.

83 {
84 return probe_providers_of<PBKDF>(algo_spec, { "base", "openssl" });
85 }

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