Botan 2.19.5 Crypto and TLS for C&

Public Member Functions | Static Public Member Functions | List of all members
Botan::RFC4880_S2K_Family Class Referencefinal

`#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 (HashFunction *hash)
std::unique_ptr< PasswordHash > | tune (size_t output_len, std::chrono::milliseconds msec, size_t max_mem) 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 136 of file pgp_s2k.h.

## Constructor & Destructor Documentation

## ◆ RFC4880_S2K_Family()

Botan::RFC4880_S2K_Family::RFC4880_S2K_Family | ( | HashFunction * | hash | ) |
| inline

Definition at line 139 of file pgp_s2k.h.

139: m_hash(hash) {}
hash
MechanismType hash
Definition: p11_mechanism.cpp:64

## Member Function Documentation

## ◆ create()

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.

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 }
BOTAN_UNUSED
#define BOTAN_UNUSED(...)
Definition: assert.h:142
Botan::HashFunction::create
static std::unique_ptr< HashFunction > create(const std::string &algo_spec, const std::string &provider="")
Definition: hash.cpp:102
Botan::MessageAuthenticationCode::create
static std::unique_ptr< MessageAuthenticationCode > create(const std::string &algo_spec, const std::string &provider="")
Definition: mac.cpp:46

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 = `""`
| ) |  |
| 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 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 }
Botan::PasswordHashFamily::create
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::RFC4880_S2K_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 188 of file pgp_s2k.cpp.

189 {
190 return std::unique_ptr<PasswordHash>(new RFC4880_S2K(m_hash->clone(), 50331648));
191 }

## ◆ from_iterations()

std::unique_ptr< PasswordHash > Botan::RFC4880_S2K_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 193 of file pgp_s2k.cpp.

194 {
195 return std::unique_ptr<PasswordHash>(new RFC4880_S2K(m_hash->clone(), iter));
196 }

## ◆ from_params()

std::unique_ptr< PasswordHash > Botan::RFC4880_S2K_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 183 of file pgp_s2k.cpp.

184 {
185 return std::unique_ptr<PasswordHash>(new RFC4880_S2K(m_hash->clone(), iter));
186 }

## ◆ name()

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

Returns
  name of this PasswordHash

Implements Botan::PasswordHashFamily.

Definition at line 154 of file pgp_s2k.cpp.

155 {
156 return "OpenPGP-S2K(" + m_hash->name() + ")";
157 }

## ◆ providers()

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

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

## ◆ tune()

std::unique_ptr< PasswordHash > Botan::RFC4880_S2K_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 159 of file pgp_s2k.cpp.

160 {
161 const auto tune_time = BOTAN_PBKDF_TUNING_TIME;
162
163 const size_t buf_size = 1024;
164 std::vector<uint8_t> buffer(buf_size);
165
166 Timer timer("RFC4880_S2K", buf_size);
167 timer.run_until_elapsed(tune_time, [&]() {
168 m_hash->update(buffer);
169 });
170
171 const double hash_bytes_per_second = timer.bytes_per_second();
172 const uint64_t desired_nsec = msec.count() * 1000000;
173
174 const size_t hash_size = m_hash->output_length();
175 const size_t blocks_required = (output_len <= hash_size ? 1 : (output_len + hash_size - 1) / hash_size);
176
177 const double bytes_to_be_hashed = (hash_bytes_per_second * (desired_nsec / 1000000000.0)) / blocks_required;
178 const size_t iterations = RFC4880_round_iterations(static_cast<size_t>(bytes_to_be_hashed));
179
180 return std::unique_ptr<PasswordHash>(new RFC4880_S2K(m_hash->clone(), iterations));
181 }
Botan::RFC4880_round_iterations
size_t RFC4880_round_iterations(size_t iterations)
Definition: pgp_s2k.h:40

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