Botan::PasswordHash Class Reference

#include <pwdhash.h>

Inheritance diagram for Botan::PasswordHash:

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)
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)
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

out	buffer to store the derived key, must be of out_len bytes
out_len	the desired length of the key to produce
password	the password to derive the key from
password_len	the length of password in bytes
salt	a randomly chosen salt
salt_len	length 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

out	buffer to store the derived key, must be of out_len bytes
out_len	the desired length of the key to produce
password	the password to derive the key from
password_len	the length of password in bytes
salt	a randomly chosen salt
salt_len	length of salt in bytes
ad	some additional data
ad_len	length of ad in bytes
key	a secret key
key_len	length 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.

   {
   BOTAN_UNUSED(ad, key);
 
   if(ad_len == 0 && key_len == 0)
      return this->derive_key(out, out_len,
                              password, password_len,
                              salt, salt_len);
   else
      throw Not_Implemented("PasswordHash " + this->to_string() + " does not support AD or key");
   }

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  )

inline

Hash a password into a bitstring

Parameters

out	a span where the derived key will be placed
password	the password to derive the key from
salt	a 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.

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

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  )

inline

Hash a password into a bitstring

Parameters

out	a span where the derived key will be placed
password	the password to derive the key from
salt	a randomly chosen salt
associated_data	some additional data
key	a 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.

         {
         this->derive_key(out.data(), out.size(),
                          password.data(), password.size(),
                          salt.data(), salt.size(),
                          associated_data.data(), associated_data.size(),
                          key.data(), key.size());
         }

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

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

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

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

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

{ return 0; }

---

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

• src/lib/pbkdf/pwdhash.h
• src/lib/pbkdf/pwdhash.cpp