Botan  2.11.0
Crypto and TLS for C++11
Public Member Functions | Static Public Member Functions | List of all members
Botan::OpenPGP_S2K Class Referencefinal

#include <pgp_s2k.h>

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

Public Member Functions

PBKDFclone () const override
 
OctetString derive_key (size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
 
template<typename Alloc >
OctetString derive_key (size_t out_len, const std::string &passphrase, const std::vector< uint8_t, Alloc > &salt, size_t iterations) const
 
OctetString derive_key (size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
 
template<typename Alloc >
OctetString derive_key (size_t out_len, const std::string &passphrase, const std::vector< uint8_t, Alloc > &salt, std::chrono::milliseconds msec, size_t &iterations) const
 
std::string name () const override
 
 OpenPGP_S2K (HashFunction *hash)
 
size_t pbkdf (uint8_t output_buf[], size_t output_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec) const override
 
void pbkdf_iterations (uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
 
secure_vector< uint8_t > pbkdf_iterations (size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
 
void pbkdf_timed (uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
 
secure_vector< uint8_t > pbkdf_timed (size_t out_len, const std::string &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 (const std::string &algo_spec, const std::string &provider="")
 
static std::unique_ptr< PBKDFcreate_or_throw (const std::string &algo_spec, const std::string &provider="")
 
static size_t decode_count (uint8_t encoded_iter)
 
static uint8_t encode_count (size_t iterations)
 
static std::vector< std::string > providers (const std::string &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 54 of file pgp_s2k.h.

Constructor & Destructor Documentation

◆ OpenPGP_S2K()

Botan::OpenPGP_S2K::OpenPGP_S2K ( HashFunction hash)
inlineexplicit
Parameters
hashthe hash function to use

Definition at line 60 of file pgp_s2k.h.

60 : m_hash(hash) {}
MechanismType hash

Member Function Documentation

◆ clone()

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

Implements Botan::PBKDF.

Definition at line 67 of file pgp_s2k.h.

68  {
69  return new OpenPGP_S2K(m_hash->clone());
70  }
OpenPGP_S2K(HashFunction *hash)
Definition: pgp_s2k.h:60

◆ create()

std::unique_ptr< PBKDF > Botan::PBKDF::create ( const std::string &  algo_spec,
const std::string &  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 26 of file pbkdf.cpp.

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::PBKDF::create_or_throw().

28  {
29  const SCAN_Name req(algo_spec);
30 
31 #if defined(BOTAN_HAS_PBKDF2)
32  if(req.algo_name() == "PBKDF2")
33  {
34  // TODO OpenSSL
35 
36  if(provider.empty() || provider == "base")
37  {
38  if(auto mac = MessageAuthenticationCode::create(req.arg(0)))
39  return std::unique_ptr<PBKDF>(new PKCS5_PBKDF2(mac.release()));
40 
41  if(auto mac = MessageAuthenticationCode::create("HMAC(" + req.arg(0) + ")"))
42  return std::unique_ptr<PBKDF>(new PKCS5_PBKDF2(mac.release()));
43  }
44 
45  return nullptr;
46  }
47 #endif
48 
49 #if defined(BOTAN_HAS_PBKDF1)
50  if(req.algo_name() == "PBKDF1" && req.arg_count() == 1)
51  {
52  if(auto hash = HashFunction::create(req.arg(0)))
53  return std::unique_ptr<PBKDF>(new PKCS5_PBKDF1(hash.release()));
54 
55  }
56 #endif
57 
58 #if defined(BOTAN_HAS_PGP_S2K)
59  if(req.algo_name() == "OpenPGP-S2K" && req.arg_count() == 1)
60  {
61  if(auto hash = HashFunction::create(req.arg(0)))
62  return std::unique_ptr<PBKDF>(new OpenPGP_S2K(hash.release()));
63  }
64 #endif
65 
66  BOTAN_UNUSED(req);
67  BOTAN_UNUSED(provider);
68 
69  return nullptr;
70  }
static std::unique_ptr< MessageAuthenticationCode > create(const std::string &algo_spec, const std::string &provider="")
Definition: mac.cpp:46
static std::unique_ptr< HashFunction > create(const std::string &algo_spec, const std::string &provider="")
Definition: hash.cpp:110
#define BOTAN_UNUSED(...)
Definition: assert.h:142
MechanismType hash

◆ create_or_throw()

std::unique_ptr< PBKDF > Botan::PBKDF::create_or_throw ( const std::string &  algo_spec,
const std::string &  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 74 of file pbkdf.cpp.

References Botan::PBKDF::create(), and Botan::PBKDF::pbkdf().

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

76  {
77  if(auto pbkdf = PBKDF::create(algo, provider))
78  {
79  return pbkdf;
80  }
81  throw Lookup_Error("PBKDF", algo, provider);
82  }
static std::unique_ptr< PBKDF > create(const std::string &algo_spec, const std::string &provider="")
Definition: pbkdf.cpp:26
virtual size_t pbkdf(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec) const =0

◆ decode_count()

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

Definition at line 86 of file pgp_s2k.h.

References Botan::RFC4880_decode_count().

87  {
88  return RFC4880_decode_count(encoded_iter);
89  }
size_t RFC4880_decode_count(uint8_t iter)
Definition: pgp_s2k.cpp:69

◆ derive_key() [1/4]

OctetString Botan::PBKDF::derive_key ( size_t  out_len,
const std::string &  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 160 of file pbkdf.h.

References salt_len.

Referenced by Botan::check_passhash9().

164  {
165  return pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations);
166  }
void pbkdf_iterations(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
Definition: pbkdf.cpp:98
size_t salt_len
Definition: x509_obj.cpp:26

◆ derive_key() [2/4]

template<typename Alloc >
OctetString Botan::PBKDF::derive_key ( size_t  out_len,
const std::string &  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 176 of file pbkdf.h.

180  {
181  return pbkdf_iterations(out_len, passphrase, salt.data(), salt.size(), iterations);
182  }
void pbkdf_iterations(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
Definition: pbkdf.cpp:98

◆ derive_key() [3/4]

OctetString Botan::PBKDF::derive_key ( size_t  out_len,
const std::string &  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 193 of file pbkdf.h.

References salt_len.

198  {
199  return pbkdf_timed(out_len, passphrase, salt, salt_len, msec, iterations);
200  }
size_t salt_len
Definition: x509_obj.cpp:26
void pbkdf_timed(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
Definition: pbkdf.cpp:89

◆ derive_key() [4/4]

template<typename Alloc >
OctetString Botan::PBKDF::derive_key ( size_t  out_len,
const std::string &  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 211 of file pbkdf.h.

216  {
217  return pbkdf_timed(out_len, passphrase, salt.data(), salt.size(), msec, iterations);
218  }
void pbkdf_timed(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
Definition: pbkdf.cpp:89

◆ 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 81 of file pgp_s2k.h.

References Botan::RFC4880_encode_count().

82  {
83  return RFC4880_encode_count(iterations);
84  }
uint8_t RFC4880_encode_count(size_t desired_iterations)
Definition: pgp_s2k.cpp:56

◆ name()

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

Implements Botan::PBKDF.

Definition at line 62 of file pgp_s2k.h.

63  {
64  return "OpenPGP-S2K(" + m_hash->name() + ")";
65  }

◆ pbkdf()

size_t Botan::OpenPGP_S2K::pbkdf ( uint8_t  out[],
size_t  out_len,
const std::string &  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 132 of file pgp_s2k.cpp.

References salt_len, and Botan::RFC4880_S2K_Family::tune().

137  {
138  std::unique_ptr<PasswordHash> pwdhash;
139 
140  if(iterations == 0)
141  {
142  RFC4880_S2K_Family s2k_params(m_hash->clone());
143  iterations = s2k_params.tune(output_len, msec, 0)->iterations();
144  }
145 
146  pgp_s2k(*m_hash, output_buf, output_len,
147  password.c_str(), password.size(),
148  salt, salt_len,
149  iterations);
150 
151  return iterations;
152  }
size_t salt_len
Definition: x509_obj.cpp:26

◆ pbkdf_iterations() [1/2]

void Botan::PBKDF::pbkdf_iterations ( uint8_t  out[],
size_t  out_len,
const std::string &  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 98 of file pbkdf.cpp.

References BOTAN_ASSERT_EQUAL, Botan::PBKDF::name(), Botan::PBKDF::pbkdf(), and salt_len.

Referenced by Botan::PBKDF::pbkdf_iterations().

102  {
103  if(iterations == 0)
104  throw Invalid_Argument(name() + ": Invalid iteration count");
105 
106  const size_t iterations_run = pbkdf(out, out_len, passphrase,
107  salt, salt_len, iterations,
108  std::chrono::milliseconds(0));
109  BOTAN_ASSERT_EQUAL(iterations, iterations_run, "Expected PBKDF iterations");
110  }
virtual std::string name() const =0
#define BOTAN_ASSERT_EQUAL(expr1, expr2, assertion_made)
Definition: assert.h:81
virtual size_t pbkdf(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec) const =0
size_t salt_len
Definition: x509_obj.cpp:26

◆ pbkdf_iterations() [2/2]

secure_vector< uint8_t > Botan::PBKDF::pbkdf_iterations ( size_t  out_len,
const std::string &  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 112 of file pbkdf.cpp.

References Botan::PBKDF::pbkdf_iterations(), and salt_len.

116  {
117  secure_vector<uint8_t> out(out_len);
118  pbkdf_iterations(out.data(), out_len, passphrase, salt, salt_len, iterations);
119  return out;
120  }
void pbkdf_iterations(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
Definition: pbkdf.cpp:98
size_t salt_len
Definition: x509_obj.cpp:26

◆ pbkdf_timed() [1/2]

void Botan::PBKDF::pbkdf_timed ( uint8_t  out[],
size_t  out_len,
const std::string &  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 89 of file pbkdf.cpp.

References Botan::PBKDF::pbkdf(), and salt_len.

Referenced by Botan::PBKDF::pbkdf_timed().

94  {
95  iterations = pbkdf(out, out_len, passphrase, salt, salt_len, 0, msec);
96  }
virtual size_t pbkdf(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec) const =0
size_t salt_len
Definition: x509_obj.cpp:26

◆ pbkdf_timed() [2/2]

secure_vector< uint8_t > Botan::PBKDF::pbkdf_timed ( size_t  out_len,
const std::string &  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 122 of file pbkdf.cpp.

References Botan::PBKDF::pbkdf_timed(), and salt_len.

127  {
128  secure_vector<uint8_t> out(out_len);
129  pbkdf_timed(out.data(), out_len, passphrase, salt, salt_len, msec, iterations);
130  return out;
131  }
size_t salt_len
Definition: x509_obj.cpp:26
void pbkdf_timed(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
Definition: pbkdf.cpp:89

◆ providers()

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

Definition at line 84 of file pbkdf.cpp.

85  {
86  return probe_providers_of<PBKDF>(algo_spec, { "base", "openssl" });
87  }

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