Botan 2.19.3
Crypto and TLS for C&
Public Member Functions | Static Public Member Functions | List of all members
Botan::Argon2_Family Class Referencefinal

#include <argon2.h>

Inheritance diagram for Botan::Argon2_Family:
Botan::PasswordHashFamily

Public Member Functions

 Argon2_Family (uint8_t family)
 
std::unique_ptr< PasswordHashdefault_params () const override
 
std::unique_ptr< PasswordHashfrom_iterations (size_t iter) const override
 
std::unique_ptr< PasswordHashfrom_params (size_t M, size_t t, 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) const override
 

Static Public Member Functions

static std::unique_ptr< PasswordHashFamilycreate (const std::string &algo_spec, const std::string &provider="")
 
static std::unique_ptr< PasswordHashFamilycreate_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 55 of file argon2.h.

Constructor & Destructor Documentation

◆ Argon2_Family()

Botan::Argon2_Family::Argon2_Family ( uint8_t  family)

Definition at line 64 of file argon2pwhash.cpp.

64 : m_family(family)
65 {
66 if(m_family != 0 && m_family != 1 && m_family != 2)
67 throw Invalid_Argument("Unknown Argon2 family identifier");
68 }

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

Definition at line 33 of file pwdhash.cpp.

35 {
36 const SCAN_Name req(algo_spec);
37
38#if defined(BOTAN_HAS_PBKDF2)
39 if(req.algo_name() == "PBKDF2")
40 {
41 if(provider.empty() || provider == "base")
42 {
43 if(auto mac = MessageAuthenticationCode::create(req.arg(0)))
44 return std::unique_ptr<PasswordHashFamily>(new PBKDF2_Family(mac.release()));
45
46 if(auto mac = MessageAuthenticationCode::create("HMAC(" + req.arg(0) + ")"))
47 return std::unique_ptr<PasswordHashFamily>(new PBKDF2_Family(mac.release()));
48 }
49
50 return nullptr;
51 }
52#endif
53
54#if defined(BOTAN_HAS_SCRYPT)
55 if(req.algo_name() == "Scrypt")
56 {
57 return std::unique_ptr<PasswordHashFamily>(new Scrypt_Family);
58 }
59#endif
60
61#if defined(BOTAN_HAS_ARGON2)
62 if(req.algo_name() == "Argon2d")
63 {
64 return std::unique_ptr<PasswordHashFamily>(new Argon2_Family(0));
65 }
66 else if(req.algo_name() == "Argon2i")
67 {
68 return std::unique_ptr<PasswordHashFamily>(new Argon2_Family(1));
69 }
70 else if(req.algo_name() == "Argon2id")
71 {
72 return std::unique_ptr<PasswordHashFamily>(new Argon2_Family(2));
73 }
74#endif
75
76#if defined(BOTAN_HAS_PBKDF_BCRYPT)
77 if(req.algo_name() == "Bcrypt-PBKDF")
78 {
79 return std::unique_ptr<PasswordHashFamily>(new Bcrypt_PBKDF_Family);
80 }
81#endif
82
83#if defined(BOTAN_HAS_PGP_S2K)
84 if(req.algo_name() == "OpenPGP-S2K" && req.arg_count() == 1)
85 {
86 if(auto hash = HashFunction::create(req.arg(0)))
87 {
88 return std::unique_ptr<PasswordHashFamily>(new RFC4880_S2K_Family(hash.release()));
89 }
90 }
91#endif
92
93 BOTAN_UNUSED(req);
94 BOTAN_UNUSED(provider);
95
96 return nullptr;
97 }
#define BOTAN_UNUSED(...)
Definition assert.h:142
static std::unique_ptr< HashFunction > create(const std::string &algo_spec, const std::string &provider="")
Definition hash.cpp:102
static std::unique_ptr< MessageAuthenticationCode > create(const std::string &algo_spec, const std::string &provider="")
Definition mac.cpp:46
MechanismType hash

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

103 {
104 if(auto pbkdf = PasswordHashFamily::create(algo, provider))
105 {
106 return pbkdf;
107 }
108 throw Lookup_Error("PasswordHashFamily", algo, provider);
109 }
static std::unique_ptr< PasswordHashFamily > create(const std::string &algo_spec, const std::string &provider="")
Definition pwdhash.cpp:33

References Botan::PasswordHashFamily::create().

◆ default_params()

std::unique_ptr< PasswordHash > Botan::Argon2_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 139 of file argon2pwhash.cpp.

140 {
141 return this->from_params(128*1024, 1, 1);
142 }
std::unique_ptr< PasswordHash > from_params(size_t M, size_t t, size_t p) const override

References from_params().

Referenced by tune().

◆ from_iterations()

std::unique_ptr< PasswordHash > Botan::Argon2_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 144 of file argon2pwhash.cpp.

145 {
146 /*
147 These choices are arbitrary, but should not change in future
148 releases since they will break applications expecting deterministic
149 mapping from iteration count to params
150 */
151 const size_t M = iter;
152 const size_t t = 1;
153 const size_t p = 1;
154 return this->from_params(M, t, p);
155 }

References from_params().

◆ from_params()

std::unique_ptr< PasswordHash > Botan::Argon2_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 157 of file argon2pwhash.cpp.

158 {
159 return std::unique_ptr<PasswordHash>(new Argon2(m_family, M, t, p));
160 }

Referenced by default_params(), from_iterations(), and tune().

◆ name()

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

Implements Botan::PasswordHashFamily.

Definition at line 70 of file argon2pwhash.cpp.

71 {
72 return argon2_family_name(m_family);
73 }

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

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

◆ tune()

std::unique_ptr< PasswordHash > Botan::Argon2_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_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.

Implements Botan::PasswordHashFamily.

Definition at line 75 of file argon2pwhash.cpp.

78 {
79 const size_t max_kib = (max_memory == 0) ? 256*1024 : max_memory*1024;
80
81 // Tune with a large memory otherwise we measure cache vs RAM speeds and underestimate
82 // costs for larger params. Default is 36 MiB, or use 128 for long times.
83 const size_t tune_M = (msec >= std::chrono::milliseconds(500) ? 128 : 36) * 1024;
84 const size_t p = 1;
85 size_t t = 1;
86
87 Timer timer("Argon2");
88 const auto tune_time = BOTAN_PBKDF_TUNING_TIME;
89
90 auto pwhash = this->from_params(tune_M, t, p);
91
92 timer.run_until_elapsed(tune_time, [&]() {
93 uint8_t output[64] = { 0 };
94 pwhash->derive_key(output, sizeof(output),
95 "test", 4,
96 nullptr, 0);
97 });
98
99 if(timer.events() == 0 || timer.value() == 0)
100 return default_params();
101
102 size_t M = 4*1024;
103
104 const uint64_t measured_time = timer.value() / (timer.events() * (tune_M / M));
105
106 const uint64_t target_nsec = msec.count() * static_cast<uint64_t>(1000000);
107
108 /*
109 * Argon2 scaling rules:
110 * k*M, k*t, k*p all increase cost by about k
111 *
112 * Since we don't even take advantage of p > 1, we prefer increasing
113 * t or M instead.
114 *
115 * If possible to increase M, prefer that.
116 */
117
118 uint64_t est_nsec = measured_time;
119
120 if(est_nsec < target_nsec && M < max_kib)
121 {
122 const uint64_t desired_cost_increase = (target_nsec + est_nsec - 1) / est_nsec;
123 const uint64_t mem_headroom = max_kib / M;
124
125 const uint64_t M_mult = std::min(desired_cost_increase, mem_headroom);
126 M *= static_cast<size_t>(M_mult);
127 est_nsec *= M_mult;
128 }
129
130 if(est_nsec < target_nsec)
131 {
132 const uint64_t desired_cost_increase = (target_nsec + est_nsec - 1) / est_nsec;
133 t *= static_cast<size_t>(desired_cost_increase);
134 }
135
136 return this->from_params(M, t, p);
137 }
std::unique_ptr< PasswordHash > default_params() const override

References 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: