Botan 2.19.5 Crypto and TLS for C&

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:

## Public Member Functions
PBKDF * | clone () const override
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
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
OctetString | derive_key (size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, 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
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
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_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_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
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

## Static Public Member Functions
static std::unique_ptr< PBKDF > | create (const std::string &algo_spec, const std::string &provider="")
static std::unique_ptr< PBKDF > | create_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 62 of file pgp_s2k.h.

## Constructor & Destructor Documentation

## ◆ OpenPGP_S2K()

Botan::OpenPGP_S2K::OpenPGP_S2K | ( | HashFunction * | hash | ) |
| inline explicit

Parameters

  hash | the hash function to use

Definition at line 68 of file pgp_s2k.h.

68: m_hash(hash) {}
hash
MechanismType hash
Definition: p11_mechanism.cpp:64

## Member Function Documentation

## ◆ clone()

PBKDF * Botan::OpenPGP_S2K::clone | ( |  | ) | const
| inline override virtual

Returns
  new instance of this same algorithm

Implements Botan::PBKDF.

Definition at line 75 of file pgp_s2k.h.

76 {
77 return new OpenPGP_S2K(m_hash->clone());
78 }
Botan::OpenPGP_S2K::OpenPGP_S2K
OpenPGP_S2K(HashFunction *hash)
Definition: pgp_s2k.h:68

## ◆ create()

std::unique_ptr< PBKDF > Botan::PBKDF::create | ( | const std::string & | algo_spec,
|  | const std::string & | provider = `""`
| ) |  |
| static inherited

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 26 of file pbkdf.cpp.

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

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().

## ◆ create_or_throw()

std::unique_ptr< PBKDF > Botan::PBKDF::create_or_throw | ( | const std::string & | algo_spec,
|  | const std::string & | provider = `""`
| ) |  |
| static inherited

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

74 {
75 if(auto pbkdf = PBKDF::create(algo, provider))
76 {
77 return pbkdf;
78 }
79 throw Lookup_Error("PBKDF", algo, provider);
80 }
Botan::PBKDF::pbkdf
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
Botan::PBKDF::create
static std::unique_ptr< PBKDF > create(const std::string &algo_spec, const std::string &provider="")
Definition: pbkdf.cpp:26

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

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

## ◆ decode_count()

static size_t Botan::OpenPGP_S2K::decode_count | ( | uint8_t | encoded_iter | ) |
| inline static

Definition at line 94 of file pgp_s2k.h.

95 {
96 return RFC4880_decode_count(encoded_iter);
97 }
Botan::RFC4880_decode_count
size_t RFC4880_decode_count(uint8_t iter)
Definition: pgp_s2k.cpp:69

References Botan::RFC4880_decode_count().

## ◆ derive_key() [1/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
| inline inherited

Derive a key from a passphrase

Parameters

  out_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  iterations | the 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 }
Botan::PBKDF::pbkdf_iterations
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:96

## ◆ 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,
|  | std::chrono::milliseconds | msec,
|  | size_t & | iterations
| ) |  | const
| inline inherited

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

Parameters

  out_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  msec | is how long to run the PBKDF
  iterations | is 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 }
Botan::PBKDF::pbkdf_timed
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:87

## ◆ 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,
|  | size_t | iterations
| ) |  | const
| inline inherited

Derive a key from a passphrase

Parameters

  out_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  iterations | the number of iterations to use (use 10K or more)

Definition at line 160 of file pbkdf.h.

164 {
165 return pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations);
166 }
salt_len
size_t salt_len
Definition: x509_obj.cpp:25

References salt_len.

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

## ◆ derive_key() [4/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
| inline inherited

Derive a key from a passphrase

Parameters

  out_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  msec | is how long to run the PBKDF
  iterations | is set to the number of iterations used

Definition at line 193 of file pbkdf.h.

198 {
199 return pbkdf_timed(out_len, passphrase, salt, salt_len, msec, iterations);
200 }

References salt_len.

## ◆ encode_count()

static uint8_t Botan::OpenPGP_S2K::encode_count | ( | size_t | iterations | ) |
| inline static

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

Definition at line 89 of file pgp_s2k.h.

90 {
91 return RFC4880_encode_count(iterations);
92 }
Botan::RFC4880_encode_count
uint8_t RFC4880_encode_count(size_t desired_iterations)
Definition: pgp_s2k.cpp:56

References Botan::RFC4880_encode_count().

## ◆ name()

std::string Botan::OpenPGP_S2K::name | ( |  | ) | const
| inline override virtual

Returns
  name of this PBKDF

Implements Botan::PBKDF.

Definition at line 70 of file pgp_s2k.h.

71 {
72 return "OpenPGP-S2K(" + m_hash->name() + ")";
73 }

## ◆ 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
| override virtual

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

  out | buffer to store the derived key, must be of out_len bytes
  out_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  iterations | the number of iterations to use (use 10K or more)
  msec | if 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.

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 }

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

## ◆ pbkdf_iterations() [1/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_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  iterations | the number of iterations to use (use 10K or more)

Returns
  the derived key

Definition at line 110 of file pbkdf.cpp.

114 {
115 secure_vector<uint8_t> out(out_len);
116 pbkdf_iterations(out.data(), out_len, passphrase, salt, salt_len, iterations);
117 return out;
118 }

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

## ◆ pbkdf_iterations() [2/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

  out | buffer to store the derived key, must be of out_len bytes
  out_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  iterations | the number of iterations to use (use 10K or more)

Definition at line 96 of file pbkdf.cpp.

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

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

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

## ◆ pbkdf_timed() [1/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_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  msec | if iterations is zero, then instead the PBKDF is run until msec milliseconds has passed.
  iterations | set to the number iterations executed

Returns
  the derived key

Definition at line 120 of file pbkdf.cpp.

125 {
126 secure_vector<uint8_t> out(out_len);
127 pbkdf_timed(out.data(), out_len, passphrase, salt, salt_len, msec, iterations);
128 return out;
129 }

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

## ◆ pbkdf_timed() [2/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

  out | buffer to store the derived key, must be of out_len bytes
  out_len | the desired length of the key to produce
  passphrase | the password to derive the key from
  salt | a randomly chosen salt
  salt_len | length of salt in bytes
  msec | if iterations is zero, then instead the PBKDF is run until msec milliseconds has passed.
  iterations | set to the number iterations executed

Definition at line 87 of file pbkdf.cpp.

92 {
93 iterations = pbkdf(out, out_len, passphrase, salt, salt_len, 0, msec);
94 }

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

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

## ◆ providers()

std::vector< std::string > Botan::PBKDF::providers | ( | const std::string & | algo_spec | ) |
| static inherited

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

Definition at line 82 of file pbkdf.cpp.

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

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

- src/lib/pbkdf/pgp_s2k/pgp_s2k.h
- src/lib/pbkdf/pgp_s2k/pgp_s2k.cpp