Botan 3.6.1
Crypto and TLS for C&
Botan::Scrypt_Family Class Referencefinal

#include <scrypt.h>

Inheritance diagram for Botan::Scrypt_Family:
Botan::PasswordHashFamily

Public Member Functions

std::unique_ptr< PasswordHashdefault_params () const override
 
std::unique_ptr< PasswordHashfrom_iterations (size_t iter) const override
 
std::unique_ptr< PasswordHashfrom_params (size_t N, size_t r, size_t p) const override
 
std::string name () const override
 
std::unique_ptr< PasswordHashtune (size_t output_length, std::chrono::milliseconds msec, size_t max_memory, std::chrono::milliseconds tune_msec) const override
 

Static Public Member Functions

static std::unique_ptr< PasswordHashFamilycreate (std::string_view algo_spec, std::string_view provider="")
 
static std::unique_ptr< PasswordHashFamilycreate_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 52 of file scrypt.h.

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_specalgorithm name
providerprovider implementation to choose
Returns
a null pointer if the algo/provider combination cannot be found

Definition at line 53 of file pwdhash.cpp.

53 {
54 const SCAN_Name req(algo_spec);
55
56#if defined(BOTAN_HAS_PBKDF2)
57 if(req.algo_name() == "PBKDF2") {
58 if(provider.empty() || provider == "base") {
59 if(auto mac = MessageAuthenticationCode::create("HMAC(" + req.arg(0) + ")")) {
60 return std::make_unique<PBKDF2_Family>(std::move(mac));
61 }
62
63 if(auto mac = MessageAuthenticationCode::create(req.arg(0))) {
64 return std::make_unique<PBKDF2_Family>(std::move(mac));
65 }
66 }
67
68 return nullptr;
69 }
70#endif
71
72#if defined(BOTAN_HAS_SCRYPT)
73 if(req.algo_name() == "Scrypt") {
74 return std::make_unique<Scrypt_Family>();
75 }
76#endif
77
78#if defined(BOTAN_HAS_ARGON2)
79 if(req.algo_name() == "Argon2d") {
80 return std::make_unique<Argon2_Family>(static_cast<uint8_t>(0));
81 } else if(req.algo_name() == "Argon2i") {
82 return std::make_unique<Argon2_Family>(static_cast<uint8_t>(1));
83 } else if(req.algo_name() == "Argon2id") {
84 return std::make_unique<Argon2_Family>(static_cast<uint8_t>(2));
85 }
86#endif
87
88#if defined(BOTAN_HAS_PBKDF_BCRYPT)
89 if(req.algo_name() == "Bcrypt-PBKDF") {
90 return std::make_unique<Bcrypt_PBKDF_Family>();
91 }
92#endif
93
94#if defined(BOTAN_HAS_PGP_S2K)
95 if(req.algo_name() == "OpenPGP-S2K" && req.arg_count() == 1) {
96 if(auto hash = HashFunction::create(req.arg(0))) {
97 return std::make_unique<RFC4880_S2K_Family>(std::move(hash));
98 }
99 }
100#endif
101
102 BOTAN_UNUSED(req);
103 BOTAN_UNUSED(provider);
104
105 return nullptr;
106}
#define BOTAN_UNUSED
Definition assert.h:118
static std::unique_ptr< HashFunction > create(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:107
static std::unique_ptr< MessageAuthenticationCode > create(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:51

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

110 {
111 if(auto pbkdf = PasswordHashFamily::create(algo, provider)) {
112 return pbkdf;
113 }
114 throw Lookup_Error("PasswordHashFamily", algo, provider);
115}
static std::unique_ptr< PasswordHashFamily > create(std::string_view algo_spec, std::string_view provider="")
Definition pwdhash.cpp:53

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::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 32 of file scrypt.cpp.

32 {
33 return std::make_unique<Scrypt>(32768, 8, 1);
34}

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

118 {
119 const size_t r = 8;
120 const size_t p = 1;
121
122 size_t N = 8192;
123
124 if(iter > 50000) {
125 N = 16384;
126 }
127 if(iter > 100000) {
128 N = 32768;
129 }
130 if(iter > 150000) {
131 N = 65536;
132 }
133
134 return std::make_unique<Scrypt>(N, r, p);
135}

◆ 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. 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 114 of file scrypt.cpp.

114 {
115 return std::make_unique<Scrypt>(N, r, p);
116}

Referenced by tune().

◆ name()

std::string Botan::Scrypt_Family::name ( ) const
overridevirtual
Returns
name of this PasswordHash

Implements Botan::PasswordHashFamily.

Definition at line 28 of file scrypt.cpp.

28 {
29 return "Scrypt";
30}

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

117 {
119}
std::vector< std::string > probe_providers_of(std::string_view algo_spec, const std::vector< std::string > &possible={"base"})
Definition scan_name.h:105

References Botan::probe_providers_of().

◆ tune()

std::unique_ptr< PasswordHash > Botan::Scrypt_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

Return a password hash instance tuned to run for approximately msec milliseconds when producing an output of length output_length. (Accuracy may vary, use the command line utility botan pbkdf_tune to check.)

The parameters will be selected to use at most max_memory_usage_mb megabytes of memory, or if left as zero any size is allowed.

This function works by runing a short tuning loop to estimate the performance of the algorithm, then scaling the parameters appropriately to hit the target size. The length of time the tuning loop runs can be controlled using the tuning_msec parameter.

Parameters
output_lengthhow long the output length will be
msecthe desired execution time in milliseconds
max_memory_usage_mbsome 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_msechow long to run the tuning loop

Implements Botan::PasswordHashFamily.

Definition at line 36 of file scrypt.cpp.

39 {
40 BOTAN_UNUSED(output_length);
41
42 /*
43 * Some rough relations between scrypt parameters and runtime.
44 * Denote here by stime(N,r,p) the msec it takes to run scrypt.
45 *
46 * Emperically for smaller sizes:
47 * stime(N,8*r,p) / stime(N,r,p) is ~ 6-7
48 * stime(N,r,8*p) / stime(N,r,8*p) is ~ 7
49 * stime(2*N,r,p) / stime(N,r,p) is ~ 2
50 *
51 * Compute stime(8192,1,1) as baseline and extrapolate
52 */
53
54 // This is zero if max_memory_usage_mb == 0 (unbounded)
55 const size_t max_memory_usage = max_memory_usage_mb * 1024 * 1024;
56
57 // Starting parameters
58 size_t N = 8 * 1024;
59 size_t r = 1;
60 size_t p = 1;
61
62 Timer timer("Scrypt");
63
64 auto pwdhash = this->from_params(N, r, p);
65
66 timer.run_until_elapsed(tune_time, [&]() {
67 uint8_t output[32] = {0};
68 pwdhash->derive_key(output, sizeof(output), "test", 4, nullptr, 0);
69 });
70
71 // No timer events seems strange, perhaps something is wrong - give
72 // up on this and just return default params
73 if(timer.events() == 0) {
74 return default_params();
75 }
76
77 // nsec per eval of scrypt with initial params
78 const uint64_t measured_time = timer.value() / timer.events();
79
80 const uint64_t target_nsec = msec.count() * static_cast<uint64_t>(1000000);
81
82 uint64_t est_nsec = measured_time;
83
84 // In below code we invoke scrypt_memory_usage with p == 0 as p contributes
85 // (very slightly) to memory consumption, but N is the driving factor.
86 // Including p leads to using an N half as large as what the user would expect.
87
88 // First increase r by 8x if possible
89 if(max_memory_usage == 0 || scrypt_memory_usage(N, r * 8, 0) <= max_memory_usage) {
90 if(target_nsec / est_nsec >= 5) {
91 r *= 8;
92 est_nsec *= 5;
93 }
94 }
95
96 // Now double N as many times as we can
97 while(max_memory_usage == 0 || scrypt_memory_usage(N * 2, r, 0) <= max_memory_usage) {
98 if(target_nsec / est_nsec >= 2) {
99 N *= 2;
100 est_nsec *= 2;
101 } else {
102 break;
103 }
104 }
105
106 // If we have extra runtime budget, increment p
107 if(target_nsec / est_nsec >= 2) {
108 p *= std::min<size_t>(1024, static_cast<size_t>(target_nsec / est_nsec));
109 }
110
111 return std::make_unique<Scrypt>(N, r, p);
112}
std::unique_ptr< PasswordHash > from_params(size_t N, size_t r, size_t p) const override
Definition scrypt.cpp:114
std::unique_ptr< PasswordHash > default_params() const override
Definition scrypt.cpp:32

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


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