Botan 3.0.0
Crypto and TLS for C&
Public Member Functions | List of all members
Botan::PBKDF2 Class Referencefinal

#include <pbkdf2.h>

Inheritance diagram for Botan::PBKDF2:
Botan::PasswordHash

Public Member Functions

void derive_key (uint8_t out[], size_t out_len, const char *password, size_t password_len, const uint8_t salt[], size_t salt_len) const override
 
virtual void derive_key (uint8_t out[], size_t out_len, const char *password, size_t password_len, const uint8_t salt[], size_t salt_len, const uint8_t ad[], size_t ad_len, const uint8_t key[], size_t key_len) const
 
void hash (std::span< uint8_t > out, std::string_view password, std::span< const uint8_t > salt)
 
void hash (std::span< uint8_t > out, std::string_view password, std::span< const uint8_t > salt, std::span< const uint8_t > associated_data, std::span< const uint8_t > key)
 
size_t iterations () const override
 
virtual size_t memory_param () const
 
virtual size_t parallelism () const
 
 PBKDF2 (const MessageAuthenticationCode &prf, size_t iter)
 
 PBKDF2 (const MessageAuthenticationCode &prf, size_t olen, std::chrono::milliseconds msec)
 
virtual bool supports_associated_data () const
 
virtual bool supports_keyed_operation () const
 
std::string to_string () const override
 
virtual size_t total_memory_usage () const
 

Detailed Description

PBKDF2

Definition at line 40 of file pbkdf2.h.

Constructor & Destructor Documentation

◆ PBKDF2() [1/2]

Botan::PBKDF2::PBKDF2 ( const MessageAuthenticationCode prf,
size_t  iter 
)
inline

Definition at line 43 of file pbkdf2.h.

43 :
44 m_prf(prf.new_object()),
45 m_iterations(iter)
46 {}

◆ PBKDF2() [2/2]

Botan::PBKDF2::PBKDF2 ( const MessageAuthenticationCode prf,
size_t  olen,
std::chrono::milliseconds  msec 
)

Definition at line 180 of file pbkdf2.cpp.

180 :
181 m_prf(prf.new_object()),
182 m_iterations(tune_pbkdf2(*m_prf, olen, msec))
183 {}

Member Function Documentation

◆ derive_key() [1/2]

void Botan::PBKDF2::derive_key ( uint8_t  out[],
size_t  out_len,
const char *  password,
size_t  password_len,
const uint8_t  salt[],
size_t  salt_len 
) const
overridevirtual

Derive a key from a password

Parameters
outbuffer to store the derived key, must be of out_len bytes
out_lenthe desired length of the key to produce
passwordthe password to derive the key from
password_lenthe length of password in bytes
salta randomly chosen salt
salt_lenlength of salt in bytes

This function is const, but is not thread safe. Different threads should either use unique objects, or serialize all access.

Implements Botan::PasswordHash.

Definition at line 190 of file pbkdf2.cpp.

193 {
194 pbkdf2_set_key(*m_prf, password, password_len);
195 pbkdf2(*m_prf, out, out_len, salt, salt_len, m_iterations);
196 }
size_t pbkdf2(MessageAuthenticationCode &prf, uint8_t out[], size_t out_len, std::string_view password, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec)
Definition: pbkdf2.cpp:81

References Botan::pbkdf2().

◆ derive_key() [2/2]

void Botan::PasswordHash::derive_key ( uint8_t  out[],
size_t  out_len,
const char *  password,
size_t  password_len,
const uint8_t  salt[],
size_t  salt_len,
const uint8_t  ad[],
size_t  ad_len,
const uint8_t  key[],
size_t  key_len 
) const
virtualinherited

Derive a key from a password plus additional data and/or a secret key

Currently this is only supported for Argon2. Using a non-empty AD or key with other algorithms will cause a Not_Implemented exception.

Parameters
outbuffer to store the derived key, must be of out_len bytes
out_lenthe desired length of the key to produce
passwordthe password to derive the key from
password_lenthe length of password in bytes
salta randomly chosen salt
salt_lenlength of salt in bytes
adsome additional data
ad_lenlength of ad in bytes
keya secret key
key_lenlength of key in bytes

This function is const, but is not thread safe. Different threads should either use unique objects, or serialize all access.

Reimplemented in Botan::Argon2.

Definition at line 33 of file pwdhash.cpp.

38 {
39 BOTAN_UNUSED(ad, key);
40
41 if(ad_len == 0 && key_len == 0)
42 return this->derive_key(out, out_len,
43 password, password_len,
44 salt, salt_len);
45 else
46 throw Not_Implemented("PasswordHash " + this->to_string() + " does not support AD or key");
47 }
#define BOTAN_UNUSED(...)
Definition: assert.h:141
virtual void derive_key(uint8_t out[], size_t out_len, const char *password, size_t password_len, const uint8_t salt[], size_t salt_len) const =0
virtual std::string to_string() const =0

References BOTAN_UNUSED, Botan::PasswordHash::derive_key(), and Botan::PasswordHash::to_string().

◆ hash() [1/2]

void Botan::PasswordHash::hash ( std::span< uint8_t >  out,
std::string_view  password,
std::span< const uint8_t >  salt 
)
inlineinherited

Hash a password into a bitstring

Parameters
outa span where the derived key will be placed
passwordthe password to derive the key from
salta randomly chosen salt

This function is const, but is not thread safe. Different threads should either use unique objects, or serialize all access.

Definition at line 82 of file pwdhash.h.

85 {
86 this->derive_key(out.data(), out.size(),
87 password.data(), password.size(),
88 salt.data(), salt.size());
89 }

◆ hash() [2/2]

void Botan::PasswordHash::hash ( std::span< uint8_t >  out,
std::string_view  password,
std::span< const uint8_t >  salt,
std::span< const uint8_t >  associated_data,
std::span< const uint8_t >  key 
)
inlineinherited

Hash a password into a bitstring

Parameters
outa span where the derived key will be placed
passwordthe password to derive the key from
salta randomly chosen salt
associated_datasome additional data
keya secret key

This function is const, but is not thread safe. Different threads should either use unique objects, or serialize all access.

Definition at line 103 of file pwdhash.h.

108 {
109 this->derive_key(out.data(), out.size(),
110 password.data(), password.size(),
111 salt.data(), salt.size(),
112 associated_data.data(), associated_data.size(),
113 key.data(), key.size());
114 }

◆ iterations()

size_t Botan::PBKDF2::iterations ( ) const
inlineoverridevirtual

Most password hashes have some notion of iterations.

Implements Botan::PasswordHash.

Definition at line 51 of file pbkdf2.h.

51{ return m_iterations; }

◆ memory_param()

virtual size_t Botan::PasswordHash::memory_param ( ) const
inlinevirtualinherited

Some password hashing algorithms have a parameter which controls how much memory is used. If not supported by some algorithm, returns 0.

Reimplemented in Botan::Argon2, Botan::Bcrypt_PBKDF, and Botan::Scrypt.

Definition at line 41 of file pwdhash.h.

41{ return 0; }

◆ parallelism()

virtual size_t Botan::PasswordHash::parallelism ( ) const
inlinevirtualinherited

Some password hashing algorithms have a parallelism parameter. If the algorithm does not support this notion, then the function returns zero. This allows distinguishing between a password hash which just does not support parallel operation, vs one that does support parallel operation but which has been configured to use a single lane.

Reimplemented in Botan::Argon2, Botan::Bcrypt_PBKDF, and Botan::Scrypt.

Definition at line 51 of file pwdhash.h.

51{ return 0; }

◆ supports_associated_data()

virtual bool Botan::PasswordHash::supports_associated_data ( ) const
inlinevirtualinherited

Returns true if this password hash supports supplying associated data

Reimplemented in Botan::Argon2.

Definition at line 70 of file pwdhash.h.

70{ return false; }

◆ supports_keyed_operation()

virtual bool Botan::PasswordHash::supports_keyed_operation ( ) const
inlinevirtualinherited

Returns true if this password hash supports supplying a key

Reimplemented in Botan::Argon2.

Definition at line 65 of file pwdhash.h.

65{ return false; }

◆ to_string()

std::string Botan::PBKDF2::to_string ( ) const
overridevirtual

Implements Botan::PasswordHash.

Definition at line 185 of file pbkdf2.cpp.

186 {
187 return fmt("PBKDF2({},{})", m_prf->name(), m_iterations);
188 }
std::string fmt(std::string_view format, const T &... args)
Definition: fmt.h:60

References Botan::fmt().

◆ total_memory_usage()

virtual size_t Botan::PasswordHash::total_memory_usage ( ) const
inlinevirtualinherited

Returns an estimate of the total number of bytes required to perform this key derivation.

If this algorithm uses a small and constant amount of memory, with no effort made towards being memory hard, this function returns 0.

Reimplemented in Botan::Argon2, Botan::Bcrypt_PBKDF, and Botan::Scrypt.

Definition at line 60 of file pwdhash.h.

60{ return 0; }

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