Botan 2.13.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

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:

## Public Member Functions
| Argon2_Family (uint8_t family)
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 M, size_t t, 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 55 of file argon2.h.

## Constructor & Destructor Documentation

Botan::Argon2_Family::Argon2_Family | ( | uint8_t | family | ) |

Definition at line 60 of file argon2pwhash.cpp.

60 : m_family(family)
61 {
62 if(m_family != 0 && m_family != 1 && m_family != 2)
63 throw Invalid_Argument("Unknown Argon2 family identifier");
64 }

## Member Function Documentation

std::unique_ptr< PasswordHashFamily > Botan::PasswordHashFamily::create | ( | const std::string & | algo_spec,
|  | const std::string & | provider = `""`
| ) |  |
| static inherited

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.

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().

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

std::unique_ptr< PasswordHashFamily > Botan::PasswordHashFamily::create_or_throw | ( | const std::string & | algo_spec,
|  | const std::string & | provider = `""`
| ) |  |
| static inherited

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.

References Botan::PasswordHashFamily::create().

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

std::unique_ptr< PasswordHash > Botan::Argon2_Family::default_params | ( |  | ) | const
| override virtual

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 131 of file argon2pwhash.cpp.

References from_params().

Referenced by tune().

132 {
133 return this->from_params(128*1024, 1, 1);
134 }
Botan::Argon2_Family::from_params
std::unique_ptr< PasswordHash > from_params(size_t M, size_t t, size_t p) const override
Definition: argon2pwhash.cpp:149

std::unique_ptr< PasswordHash > Botan::Argon2_Family::from_iterations | ( | size_t | iterations | ) | const
| override virtual

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 136 of file argon2pwhash.cpp.

References from_params().

137 {
138 /*
139 These choices are arbitrary, but should not change in future
140 releases since they will break applications expecting deterministic
141 mapping from iteration count to params
142 */
143 const size_t M = iter;
144 const size_t t = 1;
145 const size_t p = 1;
146 return this->from_params(M, t, p);
147 }
Botan::Argon2_Family::from_params
std::unique_ptr< PasswordHash > from_params(size_t M, size_t t, size_t p) const override
Definition: argon2pwhash.cpp:149

std::unique_ptr< PasswordHash > Botan::Argon2_Family::from_params | ( | size_t | i1,
|  | size_t | i2,
|  | size_t | i3
| ) |  | const
| override virtual

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 149 of file argon2pwhash.cpp.

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

150 {
151 return std::unique_ptr<PasswordHash>(new Argon2(m_family, M, t, p));
152 }

std::string Botan::Argon2_Family::name | ( |  | ) | const
| override virtual

Returns
  name of this PasswordHash

Implements Botan::PasswordHashFamily.

Definition at line 66 of file argon2pwhash.cpp.

67 {
68 return argon2_family_name(m_family);
69 }

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

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

Definition at line 113 of file pwdhash.cpp.

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

std::unique_ptr< PasswordHash > Botan::Argon2_Family::tune | ( | size_t | output_length,
|  | std::chrono::milliseconds | msec,
|  | size_t | max_memory_usage_mb
| ) |  | const
| override virtual

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 71 of file argon2pwhash.cpp.

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

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

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

- src/lib/pbkdf/argon2/argon2.h
- src/lib/pbkdf/argon2/argon2pwhash.cpp