Botan::PBKDF Class Reference

#include <pbkdf.h>

Inheritance diagram for Botan::PBKDF:

Public Member Functions
PBKDF *	clone () const
template<typename Alloc>
OctetString	derive_key (size_t out_len, std::string_view passphrase, const std::vector< uint8_t, Alloc > &salt, size_t iterations) const
template<typename Alloc>
OctetString	derive_key (size_t out_len, std::string_view passphrase, const std::vector< uint8_t, Alloc > &salt, std::chrono::milliseconds msec, size_t &iterations) const
OctetString	derive_key (size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
OctetString	derive_key (size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
virtual std::string	name () const =0
virtual std::unique_ptr< PBKDF >	new_object () const =0
virtual size_t	pbkdf (uint8_t out[], size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec) const =0
secure_vector< uint8_t >	pbkdf_iterations (size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
void	pbkdf_iterations (uint8_t out[], size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
secure_vector< uint8_t >	pbkdf_timed (size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
void	pbkdf_timed (uint8_t out[], size_t out_len, std::string_view 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 (std::string_view algo_spec, std::string_view provider="")
static std::unique_ptr< PBKDF >	create_or_throw (std::string_view algo_spec, std::string_view provider="")
static std::vector< std::string >	providers (std::string_view 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.

Starting in 2.8 this functionality is also offered by PasswordHash.

Warning

This class will be removed in a future major release. Use PasswordHash

Definition at line 34 of file pbkdf.h.

Constructor & Destructor Documentation

~PBKDF()

virtual Botan::PBKDF::~PBKDF ( )

virtualdefault

Member Function Documentation

clone()

PBKDF * Botan::PBKDF::clone ( ) const

inline

Returns

new instance of this same algorithm

Definition at line 67 of file pbkdf.h.

{ return this->new_object().release(); }

References new_object().

create()

std::unique_ptr< PBKDF > Botan::PBKDF::create ( std::string_view algo_spec, std::string_view 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 24 of file pbkdf.cpp.

                                                                                    {
   const SCAN_Name req(algo_spec);
 
#if defined(BOTAN_HAS_PBKDF2)
   if(req.algo_name() == "PBKDF2") {
      if(provider.empty() || provider == "base") {
         if(auto mac = MessageAuthenticationCode::create("HMAC(" + req.arg(0) + ")")) {
            return std::make_unique<PKCS5_PBKDF2>(std::move(mac));
         }
 
         if(auto mac = MessageAuthenticationCode::create(req.arg(0))) {
            return std::make_unique<PKCS5_PBKDF2>(std::move(mac));
         }
      }
 
      return nullptr;
   }
#endif
 
#if defined(BOTAN_HAS_PGP_S2K)
   if(req.algo_name() == "OpenPGP-S2K" && req.arg_count() == 1) {
      if(auto hash = HashFunction::create(req.arg(0))) {
         return std::make_unique<OpenPGP_S2K>(std::move(hash));
      }
   }
#endif
 
   BOTAN_UNUSED(req, provider);
 
   return nullptr;
}

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg(), Botan::SCAN_Name::arg_count(), BOTAN_UNUSED, Botan::HashFunction::create(), and Botan::MessageAuthenticationCode::create().

Referenced by create_or_throw().

create_or_throw()

std::unique_ptr< PBKDF > Botan::PBKDF::create_or_throw ( std::string_view algo_spec, std::string_view provider = "" )

static

Create an instance based on a name, or throw if the algo/provider combination cannot be found. If provider is empty then best available is chosen.

Definition at line 57 of file pbkdf.cpp.

                                                                                        {
   if(auto pbkdf = PBKDF::create(algo, provider)) {
      return pbkdf;
   }
   throw Lookup_Error("PBKDF", algo, provider);
}

References create(), and pbkdf().

Referenced by Botan::get_pbkdf(), and Botan::get_s2k().

derive_key() [1/4]

template<typename Alloc>

OctetString Botan::PBKDF::derive_key ( size_t out_len, std::string_view 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 191 of file pbkdf.h.

                                                      {
         return OctetString(pbkdf_iterations(out_len, passphrase, salt.data(), salt.size(), iterations));
      }

References pbkdf_iterations().

derive_key() [2/4]

template<typename Alloc>

OctetString Botan::PBKDF::derive_key ( size_t out_len, std::string_view 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 225 of file pbkdf.h.

                                                       {
         return OctetString(pbkdf_timed(out_len, passphrase, salt.data(), salt.size(), msec, iterations));
      }

References pbkdf_timed().

derive_key() [3/4]

OctetString Botan::PBKDF::derive_key ( size_t out_len, std::string_view 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 178 of file pbkdf.h.

                                                                                                                    {
         return OctetString(pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations));
      }

References pbkdf_iterations().

Referenced by Botan::check_passhash9(), and Botan::generate_passhash9().

derive_key() [4/4]

OctetString Botan::PBKDF::derive_key ( size_t out_len, std::string_view 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 207 of file pbkdf.h.

                                                       {
         return OctetString(pbkdf_timed(out_len, passphrase, salt, salt_len, msec, iterations));
      }

References pbkdf_timed().

name()

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

pure virtual

Returns

name of this PBKDF

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

Referenced by pbkdf_iterations().

new_object()

virtual std::unique_ptr< PBKDF > Botan::PBKDF::new_object ( ) const

pure virtual

Returns

new instance of this same algorithm

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

Referenced by clone().

pbkdf()

virtual size_t Botan::PBKDF::pbkdf ( uint8_t out[], size_t out_len, std::string_view 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::OpenPGP_S2K, and Botan::PKCS5_PBKDF2.

References pbkdf_iterations(), and pbkdf_timed().

Referenced by create_or_throw(), pbkdf_iterations(), and pbkdf_timed().

pbkdf_iterations() [1/2]

secure_vector< uint8_t > Botan::PBKDF::pbkdf_iterations	(	size_t	out_len,
		std::string_view	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 93 of file pbkdf.cpp.

                                                                                                              {
   secure_vector<uint8_t> out(out_len);
   pbkdf_iterations(out.data(), out_len, passphrase, salt, salt_len, iterations);
   return out;
}

References pbkdf_iterations().

pbkdf_iterations() [2/2]

void Botan::PBKDF::pbkdf_iterations	(	uint8_t	out[],
		size_t	out_len,
		std::string_view	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 78 of file pbkdf.cpp.

                                                      {
   if(iterations == 0) {
      throw Invalid_Argument(name() + ": Invalid iteration count");
   }
 
   const size_t iterations_run =
      pbkdf(out, out_len, passphrase, salt, salt_len, iterations, std::chrono::milliseconds(0));
   BOTAN_ASSERT_EQUAL(iterations, iterations_run, "Expected PBKDF iterations");
}

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

Referenced by derive_key(), derive_key(), pbkdf(), and pbkdf_iterations().

pbkdf_timed() [1/2]

secure_vector< uint8_t > Botan::PBKDF::pbkdf_timed	(	size_t	out_len,
		std::string_view	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 100 of file pbkdf.cpp.

                                                                    {
   secure_vector<uint8_t> out(out_len);
   pbkdf_timed(out.data(), out_len, passphrase, salt, salt_len, msec, iterations);
   return out;
}

References pbkdf_timed().

pbkdf_timed() [2/2]

void Botan::PBKDF::pbkdf_timed	(	uint8_t	out[],
		size_t	out_len,
		std::string_view	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 68 of file pbkdf.cpp.

                                                  {
   iterations = pbkdf(out, out_len, passphrase, salt, salt_len, 0, msec);
}

References pbkdf().

Referenced by derive_key(), derive_key(), pbkdf(), and pbkdf_timed().

providers()

std::vector< std::string > Botan::PBKDF::providers ( std::string_view algo_spec )

static

Returns

list of available providers for this algorithm, empty if not available

Definition at line 64 of file pbkdf.cpp.

                                                              {
   return probe_providers_of<PBKDF>(algo_spec);
}

References Botan::probe_providers_of().

---

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

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