Botan::PKCS12_KDF_Family Class Reference

#include <pkcs12_kdf.h>

Inheritance diagram for Botan::PKCS12_KDF_Family:

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 72 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 188 of file pkcs12_kdf.cpp.

                                                                                :
      m_hash(std::move(hash)), m_id(static_cast<uint8_t>(id)) {
   BOTAN_ARG_CHECK(m_hash != nullptr, "PKCS12-KDF: hash must not be null");
   BOTAN_ARG_CHECK(id >= 1 && id <= 3, "PKCS12-KDF: id must be 1 (key), 2 (IV), or 3 (MAC)");
}

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_spec	algorithm name
provider	provider implementation to choose

Returns

a null pointer if the algo/provider combination cannot be found

Definition at line 58 of file pwdhash.cpp.

                                                                                                              {
   const SCAN_Name req(algo_spec);
 
#if defined(BOTAN_HAS_PBKDF2)
   if(req.algo_name() == "PBKDF2") {
      if(provider.empty() || provider == "base") {
         if(auto mac = MessageAuthenticationCode::create("HMAC(" + req.arg(0) + ")")) {
            return std::make_unique<PBKDF2_Family>(std::move(mac));
         }
 
         if(auto mac = MessageAuthenticationCode::create(req.arg(0))) {
            return std::make_unique<PBKDF2_Family>(std::move(mac));
         }
      }
 
      return nullptr;
   }
#endif
 
#if defined(BOTAN_HAS_SCRYPT)
   if(req.algo_name() == "Scrypt") {
      return std::make_unique<Scrypt_Family>();
   }
#endif
 
#if defined(BOTAN_HAS_ARGON2)
   if(req.algo_name() == "Argon2d") {
      return std::make_unique<Argon2_Family>(static_cast<uint8_t>(0));
   } else if(req.algo_name() == "Argon2i") {
      return std::make_unique<Argon2_Family>(static_cast<uint8_t>(1));
   } else if(req.algo_name() == "Argon2id") {
      return std::make_unique<Argon2_Family>(static_cast<uint8_t>(2));
   }
#endif
 
#if defined(BOTAN_HAS_PBKDF_BCRYPT)
   if(req.algo_name() == "Bcrypt-PBKDF") {
      return std::make_unique<Bcrypt_PBKDF_Family>();
   }
#endif
 
#if defined(BOTAN_HAS_PGP_S2K)
   if(req.algo_name() == "OpenPGP-S2K" && req.arg_count() == 1) {
      if(auto hash = HashFunction::create(req.arg(0))) {
         return std::make_unique<RFC4880_S2K_Family>(std::move(hash));
      }
   }
#endif
 
#if defined(BOTAN_HAS_PKCS12_KDF)
   if(req.algo_name() == "PKCS12-KDF" && req.arg_count() == 2) {
      if(auto hash = HashFunction::create(req.arg(0))) {
         const auto id_param = req.arg_as_integer(1);
         return std::make_unique<PKCS12_KDF_Family>(std::move(hash), id_param);
      }
   }
#endif
 
   BOTAN_UNUSED(req);
   BOTAN_UNUSED(provider);
 
   return nullptr;
}

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg(), Botan::SCAN_Name::arg_as_integer(), Botan::SCAN_Name::arg_count(), BOTAN_UNUSED, Botan::HashFunction::create(), and Botan::MessageAuthenticationCode::create().

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

                                                                                                 {
   if(auto pbkdf = PasswordHashFamily::create(algo, provider)) {
      return pbkdf;
   }
   throw Lookup_Error("PasswordHashFamily", algo, provider);
}

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 228 of file pkcs12_kdf.cpp.

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

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 232 of file pkcs12_kdf.cpp.

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

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 236 of file pkcs12_kdf.cpp.

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

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 194 of file pkcs12_kdf.cpp.

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

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

                                                                           {
   return probe_providers_of<PasswordHashFamily>(algo_spec);
}

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.

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.
tuning_msec	how long to run the tuning loop

TODO(Botan4) remove this

Definition at line 282 of file pwdhash.h.

                                                                                                            {
         std::optional<size_t> max_memory_opt;
         if(max_memory_usage_mb > 0) {
            max_memory_opt = max_memory_usage_mb;
         }
 
         return this->tune_params(output_length,
                                  static_cast<uint64_t>(msec.count()),
                                  max_memory_opt,
                                  static_cast<uint64_t>(tuning_msec.count()));
      }

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.

Parameters

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

Implements Botan::PasswordHashFamily.

Definition at line 198 of file pkcs12_kdf.cpp.

                                                                                         {
   // Benchmark the real KDF at a fixed iteration count and target output length,
   // so the measurement captures hash(D || I), the full I-update carry loop, the
   // inner A-rehash loop, and the per-output-block cost.
   const size_t tuning_iterations = 10000;
   const size_t tuning_out_len = std::max<size_t>(output_length, 1);
   const std::array<uint8_t, 16> tuning_salt{};
   const std::array<uint8_t, 16> tuning_pwd{};
   const auto pwd_bytes =
      pkcs12_encode_password(std::string_view(reinterpret_cast<const char*>(tuning_pwd.data()), tuning_pwd.size()));
   std::vector<uint8_t> tuning_out(tuning_out_len);
 
   auto tuning_hash = m_hash->new_object();
   const uint64_t measured_nsec = measure_cost(tuning_msec, [&]() {
      pkcs12_kdf_with_hash(tuning_out, pwd_bytes, tuning_salt, tuning_iterations, m_id, *tuning_hash);
   });
 
   // Scale: one benchmark sample = tuning_iterations iterations; target matches desired_msec.
   const double measured = std::max<double>(1.0, static_cast<double>(measured_nsec));
   const double desired = static_cast<double>(desired_msec) * 1'000'000.0;
   const double est = (desired * static_cast<double>(tuning_iterations)) / measured;
   const double est_clamped = std::clamp(est, 1.0, static_cast<double>(std::numeric_limits<size_t>::max()));
   const size_t iterations = static_cast<size_t>(est_clamped);
 
   return std::make_unique<PKCS12_KDF>(m_hash->new_object(), m_id, iterations);
}

References Botan::measure_cost().

---

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

• src/lib/pbkdf/pkcs12_kdf/pkcs12_kdf.h
• src/lib/pbkdf/pkcs12_kdf/pkcs12_kdf.cpp