Botan 3.4.0
Crypto and TLS for C&
Public Member Functions | List of all members
Botan::PasswordHash Class Referenceabstract

#include <pwdhash.h>

Inheritance diagram for Botan::PasswordHash:
Botan::Argon2 Botan::Bcrypt_PBKDF Botan::PBKDF2 Botan::RFC4880_S2K Botan::Scrypt

Public Member Functions

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 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) const
 
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) const
 
virtual size_t iterations () const =0
 
virtual size_t memory_param () const
 
virtual size_t parallelism () const
 
virtual bool supports_associated_data () const
 
virtual bool supports_keyed_operation () const
 
virtual std::string to_string () const =0
 
virtual size_t total_memory_usage () const
 
virtual ~PasswordHash ()=default
 

Detailed Description

Base class for password based key derivation functions.

Converts a password into a key using a salt and iterated hashing to make brute force attacks harder.

Definition at line 25 of file pwdhash.h.

Constructor & Destructor Documentation

◆ ~PasswordHash()

virtual Botan::PasswordHash::~PasswordHash ( )
virtualdefault

Member Function Documentation

◆ derive_key() [1/2]

virtual 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
pure virtual

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.

Implemented in Botan::Argon2, Botan::Bcrypt_PBKDF, Botan::PBKDF2, Botan::RFC4880_S2K, and Botan::Scrypt.

Referenced by derive_key().

◆ 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
virtual

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 34 of file pwdhash.cpp.

43 {
44 BOTAN_UNUSED(ad, key);
45
46 if(ad_len == 0 && key_len == 0) {
47 return this->derive_key(out, out_len, password, password_len, salt, salt_len);
48 } else {
49 throw Not_Implemented("PasswordHash " + this->to_string() + " does not support AD or key");
50 }
51}
BOTAN_UNUSED
#define BOTAN_UNUSED
Definition assert.h:118
Botan::PasswordHash::derive_key
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
Botan::PasswordHash::to_string
virtual std::string to_string() const =0

References BOTAN_UNUSED, derive_key(), and to_string().

◆ hash() [1/2]

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

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 81 of file pwdhash.h.

81 {
82 this->derive_key(out.data(), out.size(), password.data(), password.size(), salt.data(), salt.size());
83 }

◆ 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 ) const
inline

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 97 of file pwdhash.h.

101 {
102 this->derive_key(out.data(),
103 out.size(),
104 password.data(),
105 password.size(),
106 salt.data(),
107 salt.size(),
108 associated_data.data(),
109 associated_data.size(),
110 key.data(),
111 key.size());
112 }

◆ iterations()

virtual size_t Botan::PasswordHash::iterations ( ) const
pure virtual

Most password hashes have some notion of iterations.

Implemented in Botan::Argon2, Botan::Bcrypt_PBKDF, Botan::PBKDF2, Botan::RFC4880_S2K, and Botan::Scrypt.

◆ memory_param()

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

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 40 of file pwdhash.h.

40{ return 0; }

◆ parallelism()

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

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 50 of file pwdhash.h.

50{ return 0; }

◆ supports_associated_data()

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

Returns true if this password hash supports supplying associated data

Reimplemented in Botan::Argon2.

Definition at line 69 of file pwdhash.h.

69{ return false; }

◆ supports_keyed_operation()

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

Returns true if this password hash supports supplying a key

Reimplemented in Botan::Argon2.

Definition at line 64 of file pwdhash.h.

64{ return false; }

◆ to_string()

virtual std::string Botan::PasswordHash::to_string ( ) const
pure virtual

Implemented in Botan::Argon2, Botan::Bcrypt_PBKDF, Botan::PBKDF2, Botan::RFC4880_S2K, and Botan::Scrypt.

Referenced by derive_key().

◆ total_memory_usage()

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

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 59 of file pwdhash.h.

59{ return 0; }
The documentation for this class was generated from the following files:
Generated by doxygen 1.10.0