Botan::Scrypt_Family Class Reference

#include <scrypt.h>

Inheritance diagram for Botan::Scrypt_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 N, size_t r, size_t p) const override
std::string	name () const override
std::unique_ptr< PasswordHash >	tune (size_t output_length, std::chrono::milliseconds msec, size_t max_memory) const override

Static Public Member Functions
static std::unique_ptr< PasswordHashFamily >	create (const std::string &algo_spec, const std::string &provider="")
static std::unique_ptr< PasswordHashFamily >	create_or_throw (const std::string &algo_spec, const std::string &provider="")
static std::vector< std::string >	providers (const std::string &algo_spec)

Detailed Description

Definition at line 53 of file scrypt.h.

Member Function Documentation

create()

std::unique_ptr< PasswordHashFamily > Botan::PasswordHashFamily::create ( const std::string &  algo_spec, const std::string &  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 33 of file pwdhash.cpp.

   {
   const SCAN_Name req(algo_spec);
 
#if defined(BOTAN_HAS_PBKDF2)
   if(req.algo_name() == "PBKDF2")
      {
      // TODO OpenSSL
 
      if(provider.empty() || provider == "base")
         {
         if(auto mac = MessageAuthenticationCode::create(req.arg(0)))
            return std::unique_ptr<PasswordHashFamily>(new PBKDF2_Family(mac.release()));
 
         if(auto mac = MessageAuthenticationCode::create("HMAC(" + req.arg(0) + ")"))
            return std::unique_ptr<PasswordHashFamily>(new PBKDF2_Family(mac.release()));
         }
 
      return nullptr;
      }
#endif
 
#if defined(BOTAN_HAS_SCRYPT)
   if(req.algo_name() == "Scrypt")
      {
      return std::unique_ptr<PasswordHashFamily>(new Scrypt_Family);
      }
#endif
 
#if defined(BOTAN_HAS_ARGON2)
   if(req.algo_name() == "Argon2d")
      {
      return std::unique_ptr<PasswordHashFamily>(new Argon2_Family(0));
      }
   else if(req.algo_name() == "Argon2i")
      {
      return std::unique_ptr<PasswordHashFamily>(new Argon2_Family(1));
      }
   else if(req.algo_name() == "Argon2id")
      {
      return std::unique_ptr<PasswordHashFamily>(new Argon2_Family(2));
      }
#endif
 
#if defined(BOTAN_HAS_PBKDF_BCRYPT)
   if(req.algo_name() == "Bcrypt-PBKDF")
      {
      return std::unique_ptr<PasswordHashFamily>(new 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::unique_ptr<PasswordHashFamily>(new RFC4880_S2K_Family(hash.release()));
         }
      }
#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(), Botan::MessageAuthenticationCode::create(), and hash.

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 ( const std::string &  algo_spec, const std::string &  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 103 of file pwdhash.cpp.

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

References Botan::PasswordHashFamily::create().

default_params()

std::unique_ptr< PasswordHash > Botan::Scrypt_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 24 of file scrypt.cpp.

   {
   return std::unique_ptr<PasswordHash>(new Scrypt(32768, 8, 1));
   }

Referenced by tune().

from_iterations()

std::unique_ptr< PasswordHash > Botan::Scrypt_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 110 of file scrypt.cpp.

   {
   const size_t r = 8;
   const size_t p = 1;
 
   size_t N = 8192;
 
   if(iter > 50000)
      N = 16384;
   if(iter > 100000)
      N = 32768;
   if(iter > 150000)
      N = 65536;
 
   return std::unique_ptr<PasswordHash>(new Scrypt(N, r, p));
   }

from_params()

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

overridevirtual

Create a password hash using some scheme specific format. Eg PBKDF2 and PGP-S2K set iterations in i1 Scrypt uses N,r,p in i{1-3} Bcrypt-PBKDF just has iterations Argon2{i,d,id} would use iterations, memory, parallelism for i{1-3}, and Argon2 type is part of the family.

Values not needed should be set to 0

Implements Botan::PasswordHashFamily.

Definition at line 105 of file scrypt.cpp.

   {
   return std::unique_ptr<PasswordHash>(new Scrypt(N, r, p));
   }

name()

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

overridevirtual

Returns

name of this PasswordHash

Implements Botan::PasswordHashFamily.

Definition at line 19 of file scrypt.cpp.

   {
   return "Scrypt";
   }

providers()

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

staticinherited

Returns

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

Definition at line 113 of file pwdhash.cpp.

   {
   return probe_providers_of<PasswordHashFamily>(algo_spec, { "base", "openssl" });
   }

tune()

std::unique_ptr< PasswordHash > Botan::Scrypt_Family::tune ( size_t  output_length, std::chrono::milliseconds  msec, size_t  max_memory_usage_mb  ) 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.

Implements Botan::PasswordHashFamily.

Definition at line 29 of file scrypt.cpp.

   {
   BOTAN_UNUSED(output_length);
 
   /*
   * Some rough relations between scrypt parameters and runtime.
   * Denote here by stime(N,r,p) the msec it takes to run scrypt.
   *
   * Emperically for smaller sizes:
   * stime(N,8*r,p) / stime(N,r,p) is ~ 6-7
   * stime(N,r,8*p) / stime(N,r,8*p) is ~ 7
   * stime(2*N,r,p) / stime(N,r,p) is ~ 2
   *
   * Compute stime(8192,1,1) as baseline and extrapolate
   */
 
   const size_t max_memory_usage = max_memory_usage_mb * 1024 * 1024;
   // Starting parameters
   size_t N = 8192;
   size_t r = 1;
   size_t p = 1;
 
   Timer timer("Scrypt");
   const auto tune_time = BOTAN_PBKDF_TUNING_TIME;
 
   timer.run_until_elapsed(tune_time, [&]() {
      uint8_t output[32] = { 0 };
      scrypt(output, sizeof(output), "test", 4, nullptr, 0, N, r, p);
      });
 
   // No timer events seems strange, perhaps something is wrong - give
   // up on this and just return default params
   if(timer.events() == 0)
      return default_params();
 
   // nsec per eval of scrypt with initial params
   const uint64_t measured_time = timer.value() / timer.events();
 
   const uint64_t target_nsec = msec.count() * static_cast<uint64_t>(1000000);
 
   uint64_t est_nsec = measured_time;
 
   // First move increase r by 8x if possible
 
   if(max_memory_usage == 0 || scrypt_memory_usage(N, r, p)*8 < max_memory_usage)
      {
      if(target_nsec / est_nsec >= 5)
         {
         r *= 8;
         est_nsec *= 5;
         }
      }
 
   // Now double N as many times as we can
 
   while(max_memory_usage == 0 || scrypt_memory_usage(N, r, p)*2 < max_memory_usage)
      {
      if(target_nsec / est_nsec >= 2)
         {
         N *= 2;
         est_nsec *= 2;
         }
      else
         break;
      }
 
   // If we have extra runtime budget, increment p
 
   if(target_nsec / est_nsec > 2)
      p *= std::min<size_t>(1024, static_cast<size_t>(target_nsec / est_nsec));
 
   return std::unique_ptr<PasswordHash>(new Scrypt(N, r, p));
   }

References BOTAN_UNUSED, default_params(), Botan::Timer::events(), Botan::Timer::run_until_elapsed(), Botan::scrypt(), Botan::scrypt_memory_usage(), and Botan::Timer::value().

---

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

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