Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | List of all members
Botan::PBKDF Class Referenceabstract

`#include <pbkdf.h>`

Inheritance diagram for Botan::PBKDF:

## Public Member Functions
virtual PBKDF * | clone () const =0
OctetString | derive_key (size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, 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, 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
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
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
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_iterations (size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, 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
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
virtual | ~PBKDF ()=default

## Static Public Member Functions
static std::unique_ptr< PBKDF > | create (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.

Definition at line 22 of file pbkdf.h.

## Constructor & Destructor Documentation

virtual Botan::PBKDF::~PBKDF | ( |  | ) |
| virtual default

## Member Function Documentation

virtual PBKDF* Botan::PBKDF::clone | ( |  | ) | const
| pure virtual

Returns
  new instance of this same algorithm

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

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_spec | algorithm name
  provider | provider implementation to choose

Returns
  a null pointer if the algo/provider combination cannot be found

Definition at line 21 of file pbkdf.cpp.

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 Botan::get_pbkdf().

23 {
24 const SCAN_Name req(algo_spec);
25
26 #if defined(BOTAN_HAS_PBKDF2)
27 if(req.algo_name() == "PBKDF2")
28 {
29 // TODO OpenSSL
30
31 if(provider.empty() || provider == "base")
32 {
33 if(auto mac = MessageAuthenticationCode::create(req.arg(0)))
34 return std::unique_ptr<PBKDF>(new PKCS5_PBKDF2(mac.release()));
35
36 if(auto mac = MessageAuthenticationCode::create("HMAC(" + req.arg(0) + ")"))
37 return std::unique_ptr<PBKDF>(new PKCS5_PBKDF2(mac.release()));
38 }
39
40 return nullptr;
41 }
42 #endif
43
44 #if defined(BOTAN_HAS_PBKDF1)
45 if(req.algo_name() == "PBKDF1" && req.arg_count() == 1)
46 {
47 if(auto hash = HashFunction::create(req.arg(0)))
48 return std::unique_ptr<PBKDF>(new PKCS5_PBKDF1(hash.release()));
49
50 }
51 #endif
52
53 BOTAN_UNUSED(req);
54 BOTAN_UNUSED(provider);
55
56 return nullptr;
57 }
Botan::MessageAuthenticationCode::create
static std::unique_ptr< MessageAuthenticationCode > create(const std::string &algo_spec, const std::string &provider="")
Definition: mac.cpp:43
BOTAN_UNUSED
#define BOTAN_UNUSED(v)
Definition: assert.h:92
Botan::HashFunction::create
static std::unique_ptr< HashFunction > create(const std::string &algo_spec, const std::string &provider="")
Definition: hash.cpp:93
hash
MechanismType hash
Definition: p11_mechanism.cpp:63

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_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  iterations | the number of iterations to use (use 10K or more)

Definition at line 149 of file pbkdf.h.

Referenced by Botan::check_passhash9(), Botan::CryptoBox::decrypt(), and Botan::CryptoBox::encrypt().

153 {
154 return pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations);
155 }
Botan::PBKDF::pbkdf_iterations
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:73
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_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  iterations | the number of iterations to use (use 10K or more)

Definition at line 165 of file pbkdf.h.

169 {
170 return pbkdf_iterations(out_len, passphrase, salt.data(), salt.size(), iterations);
171 }
Botan::PBKDF::pbkdf_iterations
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:73

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_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  msec | is how long to run the PBKDF
  iterations | is set to the number of iterations used

Definition at line 182 of file pbkdf.h.

187 {
188 return pbkdf_timed(out_len, passphrase, salt, salt_len, msec, iterations);
189 }
Botan::PBKDF::pbkdf_timed
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:64
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_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  msec | is how long to run the PBKDF
  iterations | is set to the number of iterations used

Definition at line 200 of file pbkdf.h.

205 {
206 return pbkdf_timed(out_len, passphrase, salt.data(), salt.size(), msec, iterations);
207 }
Botan::PBKDF::pbkdf_timed
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:64

virtual std::string Botan::PBKDF::name | ( |  | ) | const
| pure virtual

Returns
  name of this PBKDF

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

Referenced by pbkdf_iterations().

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

  out | buffer to store the derived key, must be of out_len bytes
  out_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  iterations | the number of iterations to use (use 10K or more)
  msec | if iterations is zero, then instead the PBKDF is run until msec milliseconds has passed.

Returns
  the number of iterations performed

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

Referenced by pbkdf_iterations(), and pbkdf_timed().

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

  out | buffer to store the derived key, must be of out_len bytes
  out_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  iterations | the number of iterations to use (use 10K or more)

Definition at line 73 of file pbkdf.cpp.

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

Referenced by pbkdf_iterations().

77 {
78 if(iterations == 0)
79 throw Invalid_Argument(name() + ": Invalid iteration count");
80
81 const size_t iterations_run = pbkdf(out, out_len, passphrase,
82 salt, salt_len, iterations,
83 std::chrono::milliseconds(0));
84 BOTAN_ASSERT_EQUAL(iterations, iterations_run, "Expected PBKDF iterations");
85 }
Botan::PBKDF::name
virtual std::string name() const =0
BOTAN_ASSERT_EQUAL
#define BOTAN_ASSERT_EQUAL(expr1, expr2, assertion_made)
Definition: assert.h:53
Botan::PBKDF::pbkdf
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 > 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_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  iterations | the number of iterations to use (use 10K or more)

Returns
  the derived key

Definition at line 87 of file pbkdf.cpp.

References pbkdf_iterations().

91 {
92 secure_vector<uint8_t> out(out_len);
93 pbkdf_iterations(out.data(), out_len, passphrase, salt, salt_len, iterations);
94 return out;
95 }
Botan::PBKDF::pbkdf_iterations
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:73

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

  out | buffer to store the derived key, must be of out_len bytes
  out_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  msec | if iterations is zero, then instead the PBKDF is run until msec milliseconds has passed.
  iterations | set to the number iterations executed

Definition at line 64 of file pbkdf.cpp.

References pbkdf().

Referenced by pbkdf_timed().

69 {
70 iterations = pbkdf(out, out_len, passphrase, salt, salt_len, 0, msec);
71 }
Botan::PBKDF::pbkdf
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 > 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_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  msec | if iterations is zero, then instead the PBKDF is run until msec milliseconds has passed.
  iterations | set to the number iterations executed

Returns
  the derived key

Definition at line 97 of file pbkdf.cpp.

References pbkdf_timed().

102 {
103 secure_vector<uint8_t> out(out_len);
104 pbkdf_timed(out.data(), out_len, passphrase, salt, salt_len, msec, iterations);
105 return out;
106 }
Botan::PBKDF::pbkdf_timed
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:64

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 59 of file pbkdf.cpp.

60 {
61 return probe_providers_of<PBKDF>(algo_spec, { "base", "openssl" });
62 }

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

- src/lib/pbkdf/pbkdf.h
- src/lib/pbkdf/pbkdf.cpp