#include <pgp_s2k.h>

Inheritance diagram for Botan::OpenPGP_S2K:

Public Member Functions
PBKDF *	clone () 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< 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 33 of file pgp_s2k.h.

Constructor & Destructor Documentation

◆ OpenPGP_S2K()

Botan::OpenPGP_S2K::OpenPGP_S2K ( HashFunction * hash )

inlineexplicit

Parameters

hash	the hash function to use

Definition at line 39 of file pgp_s2k.h.

39 : m_hash(hash) {}

hash

MechanismType hash

Definition: p11_mechanism.cpp:64

Member Function Documentation

◆ clone()

PBKDF* Botan::OpenPGP_S2K::clone ( ) const

inlineoverridevirtual

Returns: new instance of this same algorithm

Implements Botan::PBKDF.

Definition at line 46 of file pgp_s2k.h.

          {
          return new OpenPGP_S2K(m_hash->clone());
          }

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

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

Definition at line 25 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(), and Botan::get_pbkdf().

    {
    const SCAN_Name req(algo_spec);
 
 #if defined(BOTAN_HAS_PBKDF2)
    if(req.algo_name() == "PBKDF2")
       {
       // TODO OpenSSL
 
       if(provider.empty() || provider == "base")
          {
          if(auto mac = MessageAuthenticationCode::create(req.arg(0)))
             return std::unique_ptr<PBKDF>(new PKCS5_PBKDF2(mac.release()));
 
          if(auto mac = MessageAuthenticationCode::create("HMAC(" + req.arg(0) + ")"))
             return std::unique_ptr<PBKDF>(new PKCS5_PBKDF2(mac.release()));
          }
 
       return nullptr;
       }
 #endif
 
 #if defined(BOTAN_HAS_PBKDF1)
    if(req.algo_name() == "PBKDF1" && req.arg_count() == 1)
       {
       if(auto hash = HashFunction::create(req.arg(0)))
          return std::unique_ptr<PBKDF>(new PKCS5_PBKDF1(hash.release()));
 
       }
 #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::unique_ptr<PBKDF>(new OpenPGP_S2K(hash.release()));
       }
 #endif
 
    BOTAN_UNUSED(req);
    BOTAN_UNUSED(provider);
 
    return nullptr;
    }

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

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

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

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

◆ decode_count()

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

static

Definition at line 69 of file pgp_s2k.cpp.

    {
    return OPENPGP_S2K_ITERS[iter];
    }

◆ 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_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 158 of file pbkdf.h.

References salt_len.

Referenced by Botan::check_passhash9().

          {
          return pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations);
          }

◆ 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_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 174 of file pbkdf.h.

          {
          return pbkdf_iterations(out_len, passphrase, salt.data(), salt.size(), iterations);
          }

◆ 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_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 191 of file pbkdf.h.

References salt_len.

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

◆ 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_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 209 of file pbkdf.h.

          {
          return pbkdf_timed(out_len, passphrase, salt.data(), salt.size(), msec, iterations);
          }

◆ encode_count()

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

static

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

Definition at line 53 of file pgp_s2k.cpp.

    {
    /*
    Only 256 different iterations are actually representable in OpenPGP format ...
    */
    for(size_t c = 0; c < 256; ++c)
       {
       const uint32_t decoded_iter = OPENPGP_S2K_ITERS[c];
       if(decoded_iter >= desired_iterations)
          return static_cast<uint8_t>(c);
       }
 
    return 255;
    }

◆ name()

std::string Botan::OpenPGP_S2K::name ( ) const

inlineoverridevirtual

Returns: name of this PBKDF

Implements Botan::PBKDF.

Definition at line 41 of file pgp_s2k.h.

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

◆ 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

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 74 of file pgp_s2k.cpp.

References Botan::cast_char_ptr_to_uint8(), Botan::copy_mem(), and salt_len.

    {
    if(iterations == 0 && msec.count() > 0) // FIXME
       throw Not_Implemented("OpenPGP_S2K does not implemented timed KDF");
 
    if(iterations > 1 && salt_len == 0)
       throw Invalid_Argument("OpenPGP_S2K requires a salt in iterated mode");
 
    secure_vector<uint8_t> input_buf(salt_len + passphrase.size());
    if(salt_len > 0)
       {
       copy_mem(&input_buf[0], salt, salt_len);
       }
    if(passphrase.empty() == false)
       {
       copy_mem(&input_buf[salt_len],
                cast_char_ptr_to_uint8(passphrase.data()),
                passphrase.size());
       }
 
    secure_vector<uint8_t> hash_buf(m_hash->output_length());
 
    size_t pass = 0;
    size_t generated = 0;
 
    while(generated != output_len)
       {
       const size_t output_this_pass =
          std::min(hash_buf.size(), output_len - generated);
 
       // Preload some number of zero bytes (empty first iteration)
       std::vector<uint8_t> zero_padding(pass);
       m_hash->update(zero_padding);
 
       // The input is always fully processed even if iterations is very small
       if(input_buf.empty() == false)
          {
          size_t left = std::max(iterations, input_buf.size());
          while(left > 0)
             {
             const size_t input_to_take = std::min(left, input_buf.size());
             m_hash->update(input_buf.data(), input_to_take);
             left -= input_to_take;
             }
          }
 
       m_hash->final(hash_buf.data());
       copy_mem(output_buf + generated, hash_buf.data(), output_this_pass);
       generated += output_this_pass;
       ++pass;
       }
 
    return iterations;
    }

◆ 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

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

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

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

    {
    if(iterations == 0)
       throw Invalid_Argument(name() + ": Invalid iteration count");
 
    const size_t iterations_run = pbkdf(out, out_len, passphrase,
                                        salt, salt_len, iterations,
                                        std::chrono::milliseconds(0));
    BOTAN_ASSERT_EQUAL(iterations, iterations_run, "Expected PBKDF iterations");
    }

◆ 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_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 111 of file pbkdf.cpp.

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

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

◆ 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

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

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

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

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

◆ 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_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 121 of file pbkdf.cpp.

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

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

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

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

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

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ OpenPGP_S2K()

Member Function Documentation

◆ clone()

◆ create()

◆ create_or_throw()

◆ decode_count()

◆ derive_key() [1/4]

◆ derive_key() [2/4]

◆ derive_key() [3/4]

◆ derive_key() [4/4]

◆ encode_count()

◆ name()

◆ pbkdf()

◆ pbkdf_iterations() [1/2]

◆ pbkdf_iterations() [2/2]

◆ pbkdf_timed() [1/2]

◆ pbkdf_timed() [2/2]

◆ providers()