Botan 3.3.0
Crypto and TLS for C&
Public Member Functions | Static Public Member Functions | List of all members
Botan::PasswordHashFamily Class Referenceabstract

#include <pwdhash.h>

Inheritance diagram for Botan::PasswordHashFamily:
Botan::Argon2_Family Botan::Bcrypt_PBKDF_Family Botan::PBKDF2_Family Botan::RFC4880_S2K_Family Botan::Scrypt_Family

Public Member Functions

virtual std::unique_ptr< PasswordHashdefault_params () const =0
virtual std::unique_ptr< PasswordHashfrom_iterations (size_t iterations) const =0
virtual std::unique_ptr< PasswordHashfrom_params (size_t i1, size_t i2=0, size_t i3=0) const =0
virtual std::string name () const =0
virtual std::unique_ptr< PasswordHashtune (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 =0
virtual ~PasswordHashFamily ()=default

Static Public Member Functions

static std::unique_ptr< PasswordHashFamilycreate (std::string_view algo_spec, std::string_view provider="")
static std::unique_ptr< PasswordHashFamilycreate_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 166 of file pwdhash.h.

Constructor & Destructor Documentation

◆ ~PasswordHashFamily()

virtual Botan::PasswordHashFamily::~PasswordHashFamily ( )

Member Function Documentation

◆ create()

std::unique_ptr< PasswordHashFamily > Botan::PasswordHashFamily::create ( std::string_view algo_spec,
std::string_view provider = "" )

Create an instance based on a name If provider is empty then best available is chosen.

algo_specalgorithm name
providerprovider implementation to choose
a null pointer if the algo/provider combination cannot be found

Definition at line 53 of file pwdhash.cpp.

53 {
54 const SCAN_Name req(algo_spec);
56#if defined(BOTAN_HAS_PBKDF2)
57 if(req.algo_name() == "PBKDF2") {
58 if(provider.empty() || provider == "base") {
59 if(auto mac = MessageAuthenticationCode::create("HMAC(" + req.arg(0) + ")")) {
60 return std::make_unique<PBKDF2_Family>(std::move(mac));
61 }
63 if(auto mac = MessageAuthenticationCode::create(req.arg(0))) {
64 return std::make_unique<PBKDF2_Family>(std::move(mac));
65 }
66 }
68 return nullptr;
69 }
72#if defined(BOTAN_HAS_SCRYPT)
73 if(req.algo_name() == "Scrypt") {
74 return std::make_unique<Scrypt_Family>();
75 }
78#if defined(BOTAN_HAS_ARGON2)
79 if(req.algo_name() == "Argon2d") {
80 return std::make_unique<Argon2_Family>(static_cast<uint8_t>(0));
81 } else if(req.algo_name() == "Argon2i") {
82 return std::make_unique<Argon2_Family>(static_cast<uint8_t>(1));
83 } else if(req.algo_name() == "Argon2id") {
84 return std::make_unique<Argon2_Family>(static_cast<uint8_t>(2));
85 }
89 if(req.algo_name() == "Bcrypt-PBKDF") {
90 return std::make_unique<Bcrypt_PBKDF_Family>();
91 }
94#if defined(BOTAN_HAS_PGP_S2K)
95 if(req.algo_name() == "OpenPGP-S2K" && req.arg_count() == 1) {
96 if(auto hash = HashFunction::create(req.arg(0))) {
97 return std::make_unique<RFC4880_S2K_Family>(std::move(hash));
98 }
99 }
102 BOTAN_UNUSED(req);
103 BOTAN_UNUSED(provider);
105 return nullptr;
Definition assert.h:118
static std::unique_ptr< HashFunction > create(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:107
static std::unique_ptr< MessageAuthenticationCode > create(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:51

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg(), 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 = "" )

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

110 {
111 if(auto pbkdf = PasswordHashFamily::create(algo, provider)) {
112 return pbkdf;
113 }
114 throw Lookup_Error("PasswordHashFamily", algo, provider);
static std::unique_ptr< PasswordHashFamily > create(std::string_view algo_spec, std::string_view provider="")
Definition pwdhash.cpp:53

References create().

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

◆ default_params()

virtual std::unique_ptr< PasswordHash > Botan::PasswordHashFamily::default_params ( ) const
pure 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.

Implemented in Botan::Argon2_Family, Botan::Bcrypt_PBKDF_Family, Botan::PBKDF2_Family, Botan::RFC4880_S2K_Family, and Botan::Scrypt_Family.

◆ from_iterations()

virtual std::unique_ptr< PasswordHash > Botan::PasswordHashFamily::from_iterations ( size_t iterations) const
pure 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.

Implemented in Botan::Argon2_Family, Botan::Bcrypt_PBKDF_Family, Botan::PBKDF2_Family, Botan::RFC4880_S2K_Family, and Botan::Scrypt_Family.

◆ from_params()

virtual std::unique_ptr< PasswordHash > Botan::PasswordHashFamily::from_params ( size_t i1,
size_t i2 = 0,
size_t i3 = 0 ) const
pure virtual

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}

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

Implemented in Botan::Bcrypt_PBKDF_Family, Botan::PBKDF2_Family, Botan::RFC4880_S2K_Family, Botan::Argon2_Family, and Botan::Scrypt_Family.

◆ name()

virtual std::string Botan::PasswordHashFamily::name ( ) const
pure virtual

◆ providers()

std::vector< std::string > Botan::PasswordHashFamily::providers ( std::string_view algo_spec)
list of available providers for this algorithm, empty if not available

Definition at line 117 of file pwdhash.cpp.

117 {
118 return probe_providers_of<PasswordHashFamily>(algo_spec);

◆ tune()

virtual 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
pure virtual

Return a new parameter set tuned for this machine

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

Implemented in Botan::RFC4880_S2K_Family, Botan::PBKDF2_Family, Botan::Argon2_Family, Botan::Bcrypt_PBKDF_Family, and Botan::Scrypt_Family.

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