Botan::RFC4880_S2K_Family Class Reference

#include <pgp_s2k.h>

Inheritance diagram for Botan::RFC4880_S2K_Family:

Public Member Functions
std::unique_ptr< PasswordHash >	default_params () const override
std::unique_ptr< PasswordHash >	from_iterations (size_t iter) const override
std::unique_ptr< PasswordHash >	from_params (size_t iter, size_t, size_t) const override
std::string	name () const override
	RFC4880_S2K_Family (std::unique_ptr< HashFunction > hash)
std::unique_ptr< PasswordHash >	tune (size_t output_len, std::chrono::milliseconds msec, size_t max_mem, std::chrono::milliseconds tune_msec) const override

Static Public Member Functions
static std::unique_ptr< PasswordHashFamily >	create (std::string_view algo_spec, std::string_view provider="")
static std::unique_ptr< PasswordHashFamily >	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

Definition at line 113 of file pgp_s2k.h.

Constructor & Destructor Documentation

RFC4880_S2K_Family()

Botan::RFC4880_S2K_Family::RFC4880_S2K_Family ( std::unique_ptr< HashFunction >  hash )

inline

Definition at line 116 of file pgp_s2k.h.

: m_hash(std::move(hash)) {}

Member Function Documentation

create()

std::unique_ptr< PasswordHashFamily > Botan::PasswordHashFamily::create ( std::string_view  algo_spec, std::string_view  provider = ""  )

staticinherited

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 50 of file pwdhash.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<PBKDF2_Family>(std::move(mac));
 
         if(auto mac = MessageAuthenticationCode::create(req.arg(0)))
            return std::make_unique<PBKDF2_Family>(std::move(mac));
         }
 
      return nullptr;
      }
#endif
 
#if defined(BOTAN_HAS_SCRYPT)
   if(req.algo_name() == "Scrypt")
      {
      return std::make_unique<Scrypt_Family>();
      }
#endif
 
#if defined(BOTAN_HAS_ARGON2)
   if(req.algo_name() == "Argon2d")
      {
      return std::make_unique<Argon2_Family>(static_cast<uint8_t>(0));
      }
   else if(req.algo_name() == "Argon2i")
      {
      return std::make_unique<Argon2_Family>(static_cast<uint8_t>(1));
      }
   else if(req.algo_name() == "Argon2id")
      {
      return std::make_unique<Argon2_Family>(static_cast<uint8_t>(2));
      }
#endif
 
#if defined(BOTAN_HAS_PBKDF_BCRYPT)
   if(req.algo_name() == "Bcrypt-PBKDF")
      {
      return std::make_unique<Bcrypt_PBKDF_Family>();
      }
#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<RFC4880_S2K_Family>(std::move(hash));
         }
      }
#endif
 
   BOTAN_UNUSED(req);
   BOTAN_UNUSED(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 botan_pwdhash(), botan_pwdhash_timed(), and Botan::PasswordHashFamily::create_or_throw().

create_or_throw()

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

staticinherited

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

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

References Botan::PasswordHashFamily::create().

Referenced by Botan::argon2_check_pwhash(), Botan::argon2_generate_pwhash(), Botan::CryptoBox::decrypt_bin(), and Botan::CryptoBox::encrypt().

default_params()

std::unique_ptr< PasswordHash > Botan::RFC4880_S2K_Family::default_params ( ) const

overridevirtual

Return some default parameter set for this PBKDF that should be good enough for most users. The value returned may change over time as processing power and attacks improve.

Implements Botan::PasswordHashFamily.

Definition at line 133 of file pgp_s2k.cpp.

   {
   return std::make_unique<RFC4880_S2K>(m_hash->new_object(), 50331648);
   }

from_iterations()

std::unique_ptr< PasswordHash > Botan::RFC4880_S2K_Family::from_iterations ( size_t  iterations ) const

overridevirtual

Return a parameter chosen based on a rough approximation with the specified iteration count. The exact value this returns for a particular algorithm may change from over time. Think of it as an alternative to tune, where time is expressed in terms of PBKDF2 iterations rather than milliseconds.

Implements Botan::PasswordHashFamily.

Definition at line 138 of file pgp_s2k.cpp.

   {
   return std::make_unique<RFC4880_S2K>(m_hash->new_object(), iter);
   }

from_params()

std::unique_ptr< PasswordHash > Botan::RFC4880_S2K_Family::from_params ( size_t  i1, size_t  i2, size_t  i3  ) const

overridevirtual

Create a password hash using some scheme specific format. Parameters are as follows:

• For PBKDF2, PGP-S2K, and Bcrypt-PBKDF, i1 is iterations
• Scrypt uses N, r, p for i{1-3}
• Argon2 family uses memory (in KB), iterations, and parallelism for i{1-3}

All unneeded parameters should be set to 0 or left blank.

Implements Botan::PasswordHashFamily.

Definition at line 128 of file pgp_s2k.cpp.

   {
   return std::make_unique<RFC4880_S2K>(m_hash->new_object(), iter);
   }

name()

std::string Botan::RFC4880_S2K_Family::name ( ) const

overridevirtual

Returns

name of this PasswordHash

Implements Botan::PasswordHashFamily.

Definition at line 97 of file pgp_s2k.cpp.

   {
   return fmt("OpenPGP-S2K({})", m_hash->name());
   }

References Botan::fmt().

providers()

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

staticinherited

Returns

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

Definition at line 128 of file pwdhash.cpp.

   {
   return probe_providers_of<PasswordHashFamily>(algo_spec);
   }

tune()

std::unique_ptr< PasswordHash > Botan::RFC4880_S2K_Family::tune ( size_t  output_length, std::chrono::milliseconds  msec, size_t  max_memory_usage_mb, std::chrono::milliseconds  tuning_msec  ) const

overridevirtual

Return a new parameter set tuned for this machine

Parameters

output_length	how long the output length will be
msec	the desired execution time in milliseconds
max_memory_usage_mb	some password hash functions can use a tunable amount of memory, in this case max_memory_usage limits the amount of RAM the returned parameters will require, in mebibytes (2**20 bytes). It may require some small amount above the request. Set to zero to place no limit at all.
tuning_msec	how long to run the tuning loop

Implements Botan::PasswordHashFamily.

Definition at line 102 of file pgp_s2k.cpp.

   {
   const size_t buf_size = 1024;
   std::vector<uint8_t> buffer(buf_size);
 
   Timer timer("RFC4880_S2K", buf_size);
   timer.run_until_elapsed(tune_time, [&]() {
      m_hash->update(buffer);
      });
 
   const double hash_bytes_per_second = timer.bytes_per_second();
   const uint64_t desired_nsec = msec.count() * 1000000;
 
   const size_t hash_size = m_hash->output_length();
   const size_t blocks_required = (output_len <= hash_size ? 1 : (output_len + hash_size - 1) / hash_size);
 
   const double bytes_to_be_hashed = (hash_bytes_per_second * (desired_nsec / 1000000000.0)) / blocks_required;
   const size_t iterations = RFC4880_round_iterations(static_cast<size_t>(bytes_to_be_hashed));
 
   return std::make_unique<RFC4880_S2K>(m_hash->new_object(), iterations);
   }

References Botan::Timer::bytes_per_second(), Botan::RFC4880_round_iterations(), and Botan::Timer::run_until_elapsed().

Referenced by Botan::OpenPGP_S2K::pbkdf().

---

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

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