Botan 3.8.0
Crypto and TLS for C&
Botan::OpenPGP_S2K Class Referencefinal

#include <pgp_s2k.h>

Inheritance diagram for Botan::OpenPGP_S2K:
Botan::PBKDF

Public Member Functions

PBKDFclone () const
 
template<typename Alloc>
OctetString derive_key (size_t out_len, std::string_view passphrase, const std::vector< uint8_t, Alloc > &salt, size_t iterations) const
 
template<typename Alloc>
OctetString derive_key (size_t out_len, std::string_view passphrase, const std::vector< uint8_t, Alloc > &salt, std::chrono::milliseconds msec, size_t &iterations) const
 
OctetString derive_key (size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
 
OctetString derive_key (size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
 
std::string name () const override
 
std::unique_ptr< PBKDFnew_object () const override
 
 OpenPGP_S2K (std::unique_ptr< HashFunction > hash)
 
size_t pbkdf (uint8_t output_buf[], size_t output_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec) const override
 
secure_vector< uint8_t > pbkdf_iterations (size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
 
void pbkdf_iterations (uint8_t out[], size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
 
secure_vector< uint8_t > pbkdf_timed (size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
 
void pbkdf_timed (uint8_t out[], size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
 

Static Public Member Functions

static std::unique_ptr< PBKDFcreate (std::string_view algo_spec, std::string_view provider="")
 
static std::unique_ptr< PBKDFcreate_or_throw (std::string_view algo_spec, std::string_view provider="")
 
static size_t decode_count (uint8_t encoded_iter)
 
static uint8_t encode_count (size_t iterations)
 
static std::vector< std::string > providers (std::string_view algo_spec)
 

Detailed Description

OpenPGP's S2K

See RFC 4880 sections 3.7.1.1, 3.7.1.2, and 3.7.1.3 If the salt is empty and iterations == 1, "simple" S2K is used If the salt is non-empty and iterations == 1, "salted" S2K is used If the salt is non-empty and iterations > 1, "iterated" S2K is used

Due to complexities of the PGP S2K algorithm, time-based derivation is not supported. So if iterations == 0 and msec.count() > 0, an exception is thrown. In the future this may be supported, in which case "iterated" S2K will be used and the number of iterations performed is returned.

Note that unlike PBKDF2, OpenPGP S2K's "iterations" are defined as the number of bytes hashed.

Definition at line 39 of file pgp_s2k.h.

Constructor & Destructor Documentation

◆ OpenPGP_S2K()

Botan::OpenPGP_S2K::OpenPGP_S2K ( std::unique_ptr< HashFunction > hash)
inlineexplicit
Parameters
hashthe hash function to use

Definition at line 44 of file pgp_s2k.h.

44: m_hash(std::move(hash)) {}

Member Function Documentation

◆ clone()

PBKDF * Botan::PBKDF::clone ( ) const
inlineinherited
Returns
new instance of this same algorithm

Definition at line 65 of file pbkdf.h.

65{ return this->new_object().release(); }
virtual std::unique_ptr< PBKDF > new_object() const =0

References new_object().

◆ create()

std::unique_ptr< PBKDF > Botan::PBKDF::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 24 of file pbkdf.cpp.

24 {
25 const SCAN_Name req(algo_spec);
26
27#if defined(BOTAN_HAS_PBKDF2)
28 if(req.algo_name() == "PBKDF2") {
29 if(provider.empty() || provider == "base") {
30 if(auto mac = MessageAuthenticationCode::create("HMAC(" + req.arg(0) + ")")) {
31 return std::make_unique<PKCS5_PBKDF2>(std::move(mac));
32 }
33
34 if(auto mac = MessageAuthenticationCode::create(req.arg(0))) {
35 return std::make_unique<PKCS5_PBKDF2>(std::move(mac));
36 }
37 }
38
39 return nullptr;
40 }
41#endif
42
43#if defined(BOTAN_HAS_PGP_S2K)
44 if(req.algo_name() == "OpenPGP-S2K" && req.arg_count() == 1) {
45 if(auto hash = HashFunction::create(req.arg(0))) {
46 return std::make_unique<OpenPGP_S2K>(std::move(hash));
47 }
48 }
49#endif
50
51 BOTAN_UNUSED(req, provider);
52
53 return nullptr;
54}
#define BOTAN_UNUSED
Definition assert.h:120
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 create_or_throw().

◆ create_or_throw()

std::unique_ptr< PBKDF > Botan::PBKDF::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 57 of file pbkdf.cpp.

57 {
58 if(auto pbkdf = PBKDF::create(algo, provider)) {
59 return pbkdf;
60 }
61 throw Lookup_Error("PBKDF", algo, provider);
62}
virtual size_t pbkdf(uint8_t out[], size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec) const =0
static std::unique_ptr< PBKDF > create(std::string_view algo_spec, std::string_view provider="")
Definition pbkdf.cpp:24

References create(), and pbkdf().

Referenced by Botan::get_pbkdf(), and Botan::get_s2k().

◆ decode_count()

static size_t Botan::OpenPGP_S2K::decode_count ( uint8_t encoded_iter)
inlinestatic

Definition at line 63 of file pgp_s2k.h.

63{ return RFC4880_decode_count(encoded_iter); }
size_t RFC4880_decode_count(uint8_t iter)
Definition rfc4880.cpp:61

References Botan::RFC4880_decode_count().

◆ derive_key() [1/4]

template<typename Alloc>
OctetString Botan::PBKDF::derive_key ( size_t out_len,
std::string_view passphrase,
const std::vector< uint8_t, Alloc > & salt,
size_t iterations ) const
inlineinherited

Derive a key from a passphrase

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
iterationsthe number of iterations to use (use 10K or more)

Definition at line 189 of file pbkdf.h.

192 {
193 return OctetString(pbkdf_iterations(out_len, passphrase, salt.data(), salt.size(), iterations));
194 }
void pbkdf_iterations(uint8_t out[], size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
Definition pbkdf.cpp:78

References pbkdf_iterations().

◆ derive_key() [2/4]

template<typename Alloc>
OctetString Botan::PBKDF::derive_key ( size_t out_len,
std::string_view passphrase,
const std::vector< uint8_t, Alloc > & salt,
std::chrono::milliseconds msec,
size_t & iterations ) const
inlineinherited

Derive a key from a passphrase using a certain amount of time

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
msecis how long to run the PBKDF
iterationsis set to the number of iterations used

Definition at line 223 of file pbkdf.h.

227 {
228 return OctetString(pbkdf_timed(out_len, passphrase, salt.data(), salt.size(), msec, iterations));
229 }
void pbkdf_timed(uint8_t out[], size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
Definition pbkdf.cpp:68

References pbkdf_timed().

◆ derive_key() [3/4]

OctetString Botan::PBKDF::derive_key ( size_t out_len,
std::string_view passphrase,
const uint8_t salt[],
size_t salt_len,
size_t iterations ) const
inlineinherited

Derive a key from a passphrase

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
iterationsthe number of iterations to use (use 10K or more)

Definition at line 176 of file pbkdf.h.

177 {
178 return OctetString(pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations));
179 }

References pbkdf_iterations().

Referenced by Botan::check_passhash9(), and Botan::generate_passhash9().

◆ derive_key() [4/4]

OctetString Botan::PBKDF::derive_key ( size_t out_len,
std::string_view passphrase,
const uint8_t salt[],
size_t salt_len,
std::chrono::milliseconds msec,
size_t & iterations ) const
inlineinherited

Derive a key from a passphrase

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
msecis how long to run the PBKDF
iterationsis set to the number of iterations used

Definition at line 205 of file pbkdf.h.

210 {
211 return OctetString(pbkdf_timed(out_len, passphrase, salt, salt_len, msec, iterations));
212 }

References pbkdf_timed().

◆ encode_count()

static uint8_t Botan::OpenPGP_S2K::encode_count ( size_t iterations)
inlinestatic

RFC 4880 encodes the iteration count to a single-byte value

Definition at line 61 of file pgp_s2k.h.

61{ return RFC4880_encode_count(iterations); }
uint8_t RFC4880_encode_count(size_t desired_iterations)
Definition rfc4880.cpp:47

References Botan::RFC4880_encode_count().

◆ name()

std::string Botan::OpenPGP_S2K::name ( ) const
inlineoverridevirtual
Returns
name of this PBKDF

Implements Botan::PBKDF.

Definition at line 46 of file pgp_s2k.h.

46{ return "OpenPGP-S2K(" + m_hash->name() + ")"; }

◆ new_object()

std::unique_ptr< PBKDF > Botan::OpenPGP_S2K::new_object ( ) const
inlineoverridevirtual
Returns
new instance of this same algorithm

Implements Botan::PBKDF.

Definition at line 48 of file pgp_s2k.h.

48{ return std::make_unique<OpenPGP_S2K>(m_hash->new_object()); }

◆ pbkdf()

size_t Botan::OpenPGP_S2K::pbkdf ( uint8_t out[],
size_t out_len,
std::string_view passphrase,
const uint8_t salt[],
size_t salt_len,
size_t iterations,
std::chrono::milliseconds msec ) const
overridevirtual

Derive a key from a passphrase for a number of iterations specified by either iterations or if iterations == 0 then running until msec time has elapsed.

Parameters
outbuffer to store the derived key, must be of out_len bytes
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
iterationsthe number of iterations to use (use 10K or more)
msecif iterations is zero, then instead the PBKDF is run until msec milliseconds has passed.
Returns
the number of iterations performed

Implements Botan::PBKDF.

Definition at line 72 of file pgp_s2k.cpp.

78 {
79 std::unique_ptr<PasswordHash> pwdhash;
80
81 if(iterations == 0) {
82 RFC4880_S2K_Family s2k_params(m_hash->new_object());
83 iterations = s2k_params.tune(output_len, msec, 0, std::chrono::milliseconds(10))->iterations();
84 }
85
86 pgp_s2k(*m_hash, output_buf, output_len, password.data(), password.size(), salt, salt_len, iterations);
87
88 return iterations;
89}

References Botan::RFC4880_S2K_Family::tune().

◆ pbkdf_iterations() [1/2]

secure_vector< uint8_t > Botan::PBKDF::pbkdf_iterations ( size_t out_len,
std::string_view passphrase,
const uint8_t salt[],
size_t salt_len,
size_t iterations ) const
inherited

Derive a key from a passphrase for a number of iterations.

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
iterationsthe number of iterations to use (use 10K or more)
Returns
the derived key

Definition at line 93 of file pbkdf.cpp.

94 {
95 secure_vector<uint8_t> out(out_len);
96 pbkdf_iterations(out.data(), out_len, passphrase, salt, salt_len, iterations);
97 return out;
98}
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:64

References pbkdf_iterations().

◆ pbkdf_iterations() [2/2]

void Botan::PBKDF::pbkdf_iterations ( uint8_t out[],
size_t out_len,
std::string_view passphrase,
const uint8_t salt[],
size_t salt_len,
size_t iterations ) const
inherited

Derive a key from a passphrase for a number of iterations.

Parameters
outbuffer to store the derived key, must be of out_len bytes
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
iterationsthe number of iterations to use (use 10K or more)

Definition at line 78 of file pbkdf.cpp.

83 {
84 if(iterations == 0) {
85 throw Invalid_Argument(name() + ": Invalid iteration count");
86 }
87
88 const size_t iterations_run =
89 pbkdf(out, out_len, passphrase, salt, salt_len, iterations, std::chrono::milliseconds(0));
90 BOTAN_ASSERT_EQUAL(iterations, iterations_run, "Expected PBKDF iterations");
91}
#define BOTAN_ASSERT_EQUAL(expr1, expr2, assertion_made)
Definition assert.h:70
virtual std::string name() const =0

References BOTAN_ASSERT_EQUAL, name(), and pbkdf().

Referenced by derive_key(), derive_key(), pbkdf(), and pbkdf_iterations().

◆ pbkdf_timed() [1/2]

secure_vector< uint8_t > Botan::PBKDF::pbkdf_timed ( size_t out_len,
std::string_view passphrase,
const uint8_t salt[],
size_t salt_len,
std::chrono::milliseconds msec,
size_t & iterations ) const
inherited

Derive a key from a passphrase, running until msec time has elapsed.

Parameters
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
msecif iterations is zero, then instead the PBKDF is run until msec milliseconds has passed.
iterationsset to the number iterations executed
Returns
the derived key

Definition at line 100 of file pbkdf.cpp.

105 {
106 secure_vector<uint8_t> out(out_len);
107 pbkdf_timed(out.data(), out_len, passphrase, salt, salt_len, msec, iterations);
108 return out;
109}

References pbkdf_timed().

◆ pbkdf_timed() [2/2]

void Botan::PBKDF::pbkdf_timed ( uint8_t out[],
size_t out_len,
std::string_view passphrase,
const uint8_t salt[],
size_t salt_len,
std::chrono::milliseconds msec,
size_t & iterations ) const
inherited

Derive a key from a passphrase, running until msec time has elapsed.

Parameters
outbuffer to store the derived key, must be of out_len bytes
out_lenthe desired length of the key to produce
passphrasethe password to derive the key from
salta randomly chosen salt
salt_lenlength of salt in bytes
msecif iterations is zero, then instead the PBKDF is run until msec milliseconds has passed.
iterationsset to the number iterations executed

Definition at line 68 of file pbkdf.cpp.

74 {
75 iterations = pbkdf(out, out_len, passphrase, salt, salt_len, 0, msec);
76}

References pbkdf().

Referenced by derive_key(), derive_key(), pbkdf(), and pbkdf_timed().

◆ providers()

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

Definition at line 64 of file pbkdf.cpp.

64 {
65 return probe_providers_of<PBKDF>(algo_spec);
66}
std::vector< std::string > probe_providers_of(std::string_view algo_spec, const std::vector< std::string > &possible={"base"})
Definition scan_name.h:105

References Botan::probe_providers_of().


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