Botan 3.14.1
Crypto and TLS for C&
Botan::PKCS12_KDF_Family Class Referencefinal

#include <pkcs12_kdf.h>

Inheritance diagram for Botan::PKCS12_KDF_Family:
Botan::PasswordHashFamily

Public Member Functions

std::unique_ptr< PasswordHash > default_params () const override
std::unique_ptr< PasswordHash > from_iterations (size_t iterations) const override
std::unique_ptr< PasswordHash > from_params (size_t i1, size_t i2=0, size_t i3=0) const override
std::string name () const override
 PKCS12_KDF_Family (std::unique_ptr< HashFunction > hash, size_t id)
std::unique_ptr< PasswordHash > tune (size_t output_length, std::chrono::milliseconds msec, size_t max_memory_usage_mb=0, std::chrono::milliseconds tuning_msec=std::chrono::milliseconds(10)) const
std::unique_ptr< PasswordHash > tune_params (size_t output_length, uint64_t desired_runtime_msec, std::optional< size_t > max_memory_usage_mb={}, uint64_t tuning_msec=10) const override

Static Public Member Functions

static std::unique_ptr< PasswordHashFamily > create (std::string_view algo_spec, std::string_view provider="")
static std::unique_ptr< PasswordHashFamily > create_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 71 of file pkcs12_kdf.h.

Constructor & Destructor Documentation

◆ PKCS12_KDF_Family()

Botan::PKCS12_KDF_Family::PKCS12_KDF_Family ( std::unique_ptr< HashFunction > hash,
size_t id )

Definition at line 184 of file pkcs12_kdf.cpp.

184 :
185 m_hash(std::move(hash)), m_id(static_cast<uint8_t>(id)) {
186 BOTAN_ARG_CHECK(m_hash != nullptr, "PKCS12-KDF: hash must not be null");
187 BOTAN_ARG_CHECK(id >= 1 && id <= 3, "PKCS12-KDF: id must be 1 (key), 2 (IV), or 3 (MAC)");
188}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33

References BOTAN_ARG_CHECK.

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

60 {
61 const AlgorithmSpec req(algo_spec);
62
63#if defined(BOTAN_HAS_PBKDF2)
64 if(auto m = req.match("PBKDF2({prf})")) {
65 if(provider.empty() || provider == "base") {
66 const auto prf = m->str("prf");
67 if(auto mac = MessageAuthenticationCode::create(fmt("HMAC({})", prf))) {
68 return std::make_unique<PBKDF2_Family>(std::move(mac));
69 }
70
71 if(auto mac = MessageAuthenticationCode::create(prf)) {
72 return std::make_unique<PBKDF2_Family>(std::move(mac));
73 }
74 }
75
76 return nullptr;
77 }
78#endif
79
80#if defined(BOTAN_HAS_SCRYPT)
81 if(req.matches("Scrypt")) {
82 return std::make_unique<Scrypt_Family>();
83 }
84#endif
85
86#if defined(BOTAN_HAS_ARGON2)
87 if(req.matches("Argon2d")) {
88 return std::make_unique<Argon2_Family>(static_cast<uint8_t>(0));
89 } else if(req.matches("Argon2i")) {
90 return std::make_unique<Argon2_Family>(static_cast<uint8_t>(1));
91 } else if(req.matches("Argon2id")) {
92 return std::make_unique<Argon2_Family>(static_cast<uint8_t>(2));
93 }
94#endif
95
96#if defined(BOTAN_HAS_PBKDF_BCRYPT)
97 if(req.matches("Bcrypt-PBKDF")) {
98 return std::make_unique<Bcrypt_PBKDF_Family>();
99 }
100#endif
101
102#if defined(BOTAN_HAS_PGP_S2K)
103 if(auto m = req.match("OpenPGP-S2K({hash})")) {
104 if(auto hash = HashFunction::create(m->str("hash"))) {
105 return std::make_unique<RFC4880_S2K_Family>(std::move(hash));
106 }
107 }
108#endif
109
110#if defined(BOTAN_HAS_PKCS12_KDF)
111 if(auto m = req.match("PKCS12-KDF({hash},{id:int})")) {
112 if(auto hash = HashFunction::create(m->str("hash"))) {
113 return std::make_unique<PKCS12_KDF_Family>(std::move(hash), m->integer("id"));
114 }
115 }
116#endif
117
118 BOTAN_UNUSED(req);
119 BOTAN_UNUSED(provider);
120
121 return nullptr;
122}
#define BOTAN_UNUSED
Definition assert.h:151
static std::unique_ptr< HashFunction > create(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:112
static std::unique_ptr< MessageAuthenticationCode > create(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:51
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References BOTAN_UNUSED, Botan::HashFunction::create(), Botan::MessageAuthenticationCode::create(), Botan::fmt(), Botan::AlgorithmSpec::match(), and Botan::AlgorithmSpec::matches().

Referenced by botan_pwdhash(), botan_pwdhash_timed(), and 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 125 of file pwdhash.cpp.

126 {
127 if(auto pbkdf = PasswordHashFamily::create(algo, provider)) {
128 return pbkdf;
129 }
130 throw Lookup_Error("PasswordHashFamily", algo, provider);
131}
static std::unique_ptr< PasswordHashFamily > create(std::string_view algo_spec, std::string_view provider="")
Definition pwdhash.cpp:60

References create().

Referenced by Botan::argon2(), Botan::argon2_check_pwhash(), Botan::argon2_generate_pwhash(), Botan::bcrypt_pbkdf(), Botan::CryptoBox::decrypt_bin(), Botan::CryptoBox::encrypt(), Botan::scrypt(), and Botan::scrypt().

◆ default_params()

std::unique_ptr< PasswordHash > Botan::PKCS12_KDF_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 224 of file pkcs12_kdf.cpp.

224 {
225 return std::make_unique<PKCS12_KDF>(m_hash->new_object(), m_id, 2048);
226}

◆ from_iterations()

std::unique_ptr< PasswordHash > Botan::PKCS12_KDF_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 228 of file pkcs12_kdf.cpp.

228 {
229 return std::make_unique<PKCS12_KDF>(m_hash->new_object(), m_id, iterations);
230}

◆ from_params()

std::unique_ptr< PasswordHash > Botan::PKCS12_KDF_Family::from_params ( size_t i1,
size_t i2 = 0,
size_t i3 = 0 ) 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}
  • PKCS12-KDF uses iterations for i1 (the hash and id are fixed by the family name, e.g. "PKCS12-KDF(SHA-256,1)")

All unneeded parameters should be set to 0 or left blank.

Implements Botan::PasswordHashFamily.

Definition at line 232 of file pkcs12_kdf.cpp.

232 {
233 return std::make_unique<PKCS12_KDF>(m_hash->new_object(), m_id, i1);
234}

◆ name()

std::string Botan::PKCS12_KDF_Family::name ( ) const
overridevirtual

Return the name of this password hash family

Returns
name of this PasswordHash

Implements Botan::PasswordHashFamily.

Definition at line 190 of file pkcs12_kdf.cpp.

190 {
191 return fmt("PKCS12-KDF({},{})", m_hash->name(), static_cast<unsigned>(m_id));
192}

References Botan::fmt().

◆ providers()

std::vector< std::string > Botan::PasswordHashFamily::providers ( std::string_view algo_spec)
staticinherited

List the providers available for a given password hash

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

Definition at line 133 of file pwdhash.cpp.

133 {
135}
std::vector< std::string > probe_providers_of(std::string_view algo_spec, const std::vector< std::string > &possible={"base"})

References Botan::probe_providers_of().

◆ tune()

std::unique_ptr< PasswordHash > Botan::PasswordHashFamily::tune ( size_t output_length,
std::chrono::milliseconds msec,
size_t max_memory_usage_mb = 0,
std::chrono::milliseconds tuning_msec = std::chrono::milliseconds(10) ) const
inlineinherited

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 running 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, though it always runs at least a few iterations and so may take longer for expensive functions.

The tuning loop measures the CPU time of the calling thread (where the platform supports this) and uses the fastest iteration observed, so the result reflects the capacity of the machine rather than its load at the moment of tuning. On a heavily loaded system the returned parameters may therefore take longer than requested.

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

TODO(Botan4) remove this

Definition at line 296 of file pwdhash.h.

299 {
300 std::optional<size_t> max_memory_opt;
301 if(max_memory_usage_mb > 0) {
302 max_memory_opt = max_memory_usage_mb;
303 }
304
305 return this->tune_params(output_length,
306 static_cast<uint64_t>(msec.count()),
307 max_memory_opt,
308 static_cast<uint64_t>(tuning_msec.count()));
309 }
virtual std::unique_ptr< PasswordHash > tune_params(size_t output_length, uint64_t desired_runtime_msec, std::optional< size_t > max_memory_usage_mb={}, uint64_t tuning_msec=10) const =0

References tune(), and tune_params().

Referenced by tune().

◆ tune_params()

std::unique_ptr< PasswordHash > Botan::PKCS12_KDF_Family::tune_params ( size_t output_length,
uint64_t desired_runtime_msec,
std::optional< size_t > max_memory_usage_mb = {},
uint64_t tuning_msec = 10 ) 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 running 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, though it always runs at least a few iterations and so may take longer for expensive functions.

The tuning loop measures the CPU time of the calling thread (where the platform supports this) and uses the fastest iteration observed, so the result reflects the capacity of the machine rather than its load at the moment of tuning. On a heavily loaded system the returned parameters may therefore take longer than requested.

Parameters
output_lengthhow long the output length will be
desired_runtime_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 nullopt to place no limit at all.
tuning_msechow long to run the tuning loop

Implements Botan::PasswordHashFamily.

Definition at line 194 of file pkcs12_kdf.cpp.

197 {
198 // Benchmark the real KDF at a fixed iteration count and target output length,
199 // so the measurement captures hash(D || I), the full I-update carry loop, the
200 // inner A-rehash loop, and the per-output-block cost.
201 const size_t tuning_iterations = 10000;
202 const size_t tuning_out_len = std::max<size_t>(output_length, 1);
203 const std::array<uint8_t, 16> tuning_salt{};
204 const std::array<uint8_t, 16> tuning_pwd{};
205 const auto pwd_bytes =
206 pkcs12_encode_password(std::string_view(reinterpret_cast<const char*>(tuning_pwd.data()), tuning_pwd.size()));
207 std::vector<uint8_t> tuning_out(tuning_out_len);
208
209 auto tuning_hash = m_hash->new_object();
210 const uint64_t measured_nsec = measure_cost(tuning_msec, [&]() {
211 pkcs12_kdf_with_hash(tuning_out, pwd_bytes, tuning_salt, tuning_iterations, m_id, *tuning_hash);
212 });
213
214 // Scale: one benchmark sample = tuning_iterations iterations; target matches desired_msec.
215 const double measured = std::max<double>(1.0, static_cast<double>(measured_nsec));
216 const double desired = static_cast<double>(desired_msec) * 1'000'000.0;
217 const double est = (desired * static_cast<double>(tuning_iterations)) / measured;
218 const double est_clamped = std::clamp(est, 1.0, static_cast<double>(std::numeric_limits<size_t>::max()));
219 const size_t iterations = static_cast<size_t>(est_clamped);
220
221 return std::make_unique<PKCS12_KDF>(m_hash->new_object(), m_id, iterations);
222}
uint64_t measure_cost(uint64_t trial_msec, F func)
Definition time_utils.h:34

References Botan::measure_cost().


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