Botan::Bcrypt_PBKDF Class Reference

#include <bcrypt_pbkdf.h>

Inheritance diagram for Botan::Bcrypt_PBKDF:

Public Member Functions
	Bcrypt_PBKDF (const Bcrypt_PBKDF &other)=default
	Bcrypt_PBKDF (size_t iterations)
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) 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
size_t	iterations () const override
size_t	memory_param () const override
Bcrypt_PBKDF &	operator= (const Bcrypt_PBKDF &)=default
size_t	parallelism () const override
virtual bool	supports_associated_data () const
virtual bool	supports_keyed_operation () const
std::string	to_string () const override
size_t	total_memory_usage () const override

Detailed Description

Bcrypt-PBKDF key derivation function

Definition at line 20 of file bcrypt_pbkdf.h.

Constructor & Destructor Documentation

Bcrypt_PBKDF() [1/2]

Botan::Bcrypt_PBKDF::Bcrypt_PBKDF

(

size_t

iterations

)

Definition at line 17 of file bcrypt_pbkdf.cpp.

                                            : m_iterations(iterations) {
   BOTAN_ARG_CHECK(m_iterations > 0, "Invalid Bcrypt-PBKDF iterations");
}

References BOTAN_ARG_CHECK.

Bcrypt_PBKDF() [2/2]

Botan::Bcrypt_PBKDF::Bcrypt_PBKDF ( const Bcrypt_PBKDF & other )

default

Member Function Documentation

derive_key() [1/2]

void Botan::Bcrypt_PBKDF::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 new key under the current Bcrypt-PBKDF parameter set

Implements Botan::PasswordHash.

Definition at line 120 of file bcrypt_pbkdf.cpp.

                                                     {
   // No output desired, so we are all done already...
   if(output_len == 0) {
      return;
   }
 
   BOTAN_ARG_CHECK(output_len <= 10 * 1024 * 1024, "Too much output for Bcrypt PBKDF");
 
   const size_t BCRYPT_BLOCK_SIZE = 32;
   const size_t blocks = (output_len + BCRYPT_BLOCK_SIZE - 1) / BCRYPT_BLOCK_SIZE;
 
   auto sha512 = HashFunction::create_or_throw("SHA-512");
   const auto pass_hash = sha512->process(reinterpret_cast<const uint8_t*>(password), password_len);
 
   secure_vector<uint8_t> salt_hash(sha512->output_length());
 
   Blowfish blowfish;
   secure_vector<uint8_t> out(BCRYPT_BLOCK_SIZE);
   secure_vector<uint8_t> tmp(BCRYPT_BLOCK_SIZE);
 
   for(size_t block = 0; block != blocks; ++block) {
      clear_mem(out.data(), out.size());
 
      sha512->update(salt, salt_len);
      sha512->update_be(static_cast<uint32_t>(block + 1));
      sha512->final(salt_hash.data());
 
      bcrypt_round(blowfish, pass_hash, salt_hash, out, tmp);
 
      for(size_t r = 1; r < m_iterations; ++r) {
         // Next salt is H(prev_output)
         sha512->update(tmp);
         sha512->final(salt_hash.data());
 
         bcrypt_round(blowfish, pass_hash, salt_hash, out, tmp);
      }
 
      for(size_t i = 0; i != BCRYPT_BLOCK_SIZE; ++i) {
         const size_t dest = i * blocks + block;
         if(dest < output_len) {
            output[dest] = out[i];
         }
      }
   }
}

References BOTAN_ARG_CHECK, Botan::clear_mem(), and Botan::HashFunction::create_or_throw().

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

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 34 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, 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 ) const

inlineinherited

Hash a password into a bitstring

Derive a key from the specified password and salt, placing it into out.

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

inlineinherited

Hash a password into a bitstring

Derive a key from the specified password, salt, associated_data, and secret key, placing it into out. The associated_data and key are both allowed to be empty. Currently non-empty AD/key is only supported with Argon2.

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

size_t Botan::Bcrypt_PBKDF::iterations ( ) const

inlineoverridevirtual

Most password hashes have some notion of iterations.

Implements Botan::PasswordHash.

Definition at line 39 of file bcrypt_pbkdf.h.

{ return m_iterations; }

memory_param()

size_t Botan::Bcrypt_PBKDF::memory_param ( ) const

inlineoverridevirtual

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

Reimplemented from Botan::PasswordHash.

Definition at line 43 of file bcrypt_pbkdf.h.

{ return 0; }

operator=()

Bcrypt_PBKDF & Botan::Bcrypt_PBKDF::operator= ( const Bcrypt_PBKDF & )

default

parallelism()

size_t Botan::Bcrypt_PBKDF::parallelism ( ) const

inlineoverridevirtual

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 from Botan::PasswordHash.

Definition at line 41 of file bcrypt_pbkdf.h.

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

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

{ return false; }

to_string()

std::string Botan::Bcrypt_PBKDF::to_string ( ) const

overridevirtual

Implements Botan::PasswordHash.

Definition at line 21 of file bcrypt_pbkdf.cpp.

                                        {
   return fmt("Bcrypt-PBKDF({})", m_iterations);
}

References Botan::fmt().

total_memory_usage()

size_t Botan::Bcrypt_PBKDF::total_memory_usage ( ) const

inlineoverridevirtual

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 from Botan::PasswordHash.

Definition at line 45 of file bcrypt_pbkdf.h.

{ return 4096; }

---

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

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