Botan::PKCS8 Namespace Reference

Functions
secure_vector< uint8_t >	BER_encode (const Private_Key &key)
std::vector< uint8_t >	BER_encode (const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, std::chrono::milliseconds msec, const std::string &pbe_algo)
std::vector< uint8_t >	BER_encode_encrypted_pbkdf_iter (const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, size_t pbkdf_iterations, const std::string &cipher, const std::string &pbkdf_hash)
std::vector< uint8_t >	BER_encode_encrypted_pbkdf_msec (const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, std::chrono::milliseconds pbkdf_msec, size_t *pbkdf_iterations, const std::string &cipher, const std::string &pbkdf_hash)
std::unique_ptr< Private_Key >	copy_key (const Private_Key &key)
Private_Key *	copy_key (const Private_Key &key, RandomNumberGenerator &rng)
std::unique_ptr< Private_Key >	load_key (DataSource &source)
std::unique_ptr< Private_Key >	load_key (DataSource &source, const std::function< std::string()> &get_pass)
std::unique_ptr< Private_Key >	load_key (DataSource &source, const std::string &pass)
Private_Key *	load_key (DataSource &source, RandomNumberGenerator &rng)
Private_Key *	load_key (DataSource &source, RandomNumberGenerator &rng, const std::string &pass)
Private_Key *	load_key (DataSource &source, RandomNumberGenerator &rng, std::function< std::string()> get_passphrase)
std::string	PEM_encode (const Private_Key &key)
std::string	PEM_encode (const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, std::chrono::milliseconds msec, const std::string &pbe_algo)
std::string	PEM_encode_encrypted_pbkdf_iter (const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, size_t pbkdf_iterations, const std::string &cipher, const std::string &pbkdf_hash)
std::string	PEM_encode_encrypted_pbkdf_msec (const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, std::chrono::milliseconds pbkdf_msec, size_t *pbkdf_iterations, const std::string &cipher, const std::string &pbkdf_hash)

Detailed Description

This namespace contains functions for handling PKCS #8 private keys

Function Documentation

BER_encode() [1/2]

secure_vector< uint8_t > Botan::PKCS8::BER_encode ( const Private_Key &  key )

inline

BER encode a private key

Parameters

key	the private key to encode

Returns

BER encoded key

Definition at line 43 of file pkcs8.h.

   {
   return key.private_key_info();
   }

References Botan::Private_Key::private_key_info().

BER_encode() [2/2]

std::vector< uint8_t > Botan::PKCS8::BER_encode	(	const Private_Key &	key,
		RandomNumberGenerator &	rng,
		const std::string &	pass,
		std::chrono::milliseconds	msec = std::chrono::milliseconds(300),
		const std::string &	pbe_algo = ""
	)

Encrypt a key using PKCS #8 encryption

Parameters

key	the key to encode
rng	the rng to use
pass	the password to use for encryption
msec	number of milliseconds to run the password derivation
pbe_algo	the name of the desired password-based encryption algorithm; if empty ("") a reasonable (portable/secure) default will be chosen.

Returns

encrypted key in binary BER form

Definition at line 189 of file pkcs8.cpp.

   {
#if defined(BOTAN_HAS_PKCS5_PBES2)
   const auto pbe_params = choose_pbe_params(pbe_algo, key.algo_name());
 
   const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
      pbes2_encrypt_msec(PKCS8::BER_encode(key), pass, msec, nullptr,
                         pbe_params.first, pbe_params.second, rng);
 
   std::vector<uint8_t> output;
   DER_Encoder der(output);
   der.start_sequence()
         .encode(pbe_info.first)
         .encode(pbe_info.second, ASN1_Type::OctetString)
      .end_cons();
 
   return output;
#else
   BOTAN_UNUSED(key, rng, pass, msec, pbe_algo);
   throw Encoding_Error("PKCS8::BER_encode cannot encrypt because PBES2 was disabled in build");
#endif
   }

References Botan::Public_Key::algo_name(), BER_encode(), BOTAN_UNUSED, Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::OctetString, Botan::pbes2_encrypt_msec(), and Botan::DER_Encoder::start_sequence().

Referenced by BER_encode(), botan_privkey_export(), Botan::Certificate_Store_In_SQL::insert_key(), and PEM_encode().

BER_encode_encrypted_pbkdf_iter()

std::vector< uint8_t > Botan::PKCS8::BER_encode_encrypted_pbkdf_iter	(	const Private_Key &	key,
		RandomNumberGenerator &	rng,
		const std::string &	pass,
		size_t	pbkdf_iter,
		const std::string &	cipher = "",
		const std::string &	pbkdf_hash = ""
	)

Encrypt a key using PKCS #8 encryption and a fixed iteration count

Parameters

key	the key to encode
rng	the rng to use
pass	the password to use for encryption
pbkdf_iter	number of interations to run PBKDF2
cipher	if non-empty specifies the cipher to use. CBC and GCM modes are supported, for example "AES-128/CBC", "AES-256/GCM", "Serpent/CBC". If empty a suitable default is chosen.
pbkdf_hash	if non-empty specifies the PBKDF hash function to use. For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.

Returns

encrypted key in binary BER form

Definition at line 235 of file pkcs8.cpp.

   {
#if defined(BOTAN_HAS_PKCS5_PBES2)
   const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
      pbes2_encrypt_iter(key.private_key_info(),
                         pass, pbkdf_iterations,
                         cipher.empty() ? "AES-256/CBC" : cipher,
                         pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
                         rng);
 
   std::vector<uint8_t> output;
   DER_Encoder der(output);
   der.start_sequence()
         .encode(pbe_info.first)
         .encode(pbe_info.second, ASN1_Type::OctetString)
      .end_cons();
 
   return output;
 
#else
   BOTAN_UNUSED(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash);
   throw Encoding_Error("PKCS8::BER_encode_encrypted_pbkdf_iter cannot encrypt because PBES2 disabled in build");
#endif
   }

References BOTAN_UNUSED, Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::OctetString, Botan::pbes2_encrypt_iter(), Botan::Private_Key::private_key_info(), and Botan::DER_Encoder::start_sequence().

Referenced by botan_privkey_export_encrypted_pbkdf_iter(), and PEM_encode_encrypted_pbkdf_iter().

BER_encode_encrypted_pbkdf_msec()

std::vector< uint8_t > Botan::PKCS8::BER_encode_encrypted_pbkdf_msec	(	const Private_Key &	key,
		RandomNumberGenerator &	rng,
		const std::string &	pass,
		std::chrono::milliseconds	pbkdf_msec,
		size_t *	pbkdf_iterations,
		const std::string &	cipher = "",
		const std::string &	pbkdf_hash = ""
	)

Encrypt a key using PKCS #8 encryption and a variable iteration count

Parameters

key	the key to encode
rng	the rng to use
pass	the password to use for encryption
pbkdf_msec	how long to run PBKDF2
pbkdf_iterations	if non-null, set to the number of iterations used
cipher	if non-empty specifies the cipher to use. CBC and GCM modes are supported, for example "AES-128/CBC", "AES-256/GCM", "Serpent/CBC". If empty a suitable default is chosen.
pbkdf_hash	if non-empty specifies the PBKDF hash function to use. For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.

Returns

encrypted key in binary BER form

Definition at line 283 of file pkcs8.cpp.

   {
#if defined(BOTAN_HAS_PKCS5_PBES2)
   const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
      pbes2_encrypt_msec(key.private_key_info(), pass,
                         pbkdf_msec, pbkdf_iterations,
                         cipher.empty() ? "AES-256/CBC" : cipher,
                         pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
                         rng);
 
   std::vector<uint8_t> output;
   DER_Encoder(output)
      .start_sequence()
         .encode(pbe_info.first)
         .encode(pbe_info.second, ASN1_Type::OctetString)
      .end_cons();
 
   return output;
#else
   BOTAN_UNUSED(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash);
   throw Encoding_Error("BER_encode_encrypted_pbkdf_msec cannot encrypt because PBES2 disabled in build");
#endif
   }

References BOTAN_UNUSED, Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::OctetString, Botan::pbes2_encrypt_msec(), Botan::Private_Key::private_key_info(), and Botan::DER_Encoder::start_sequence().

Referenced by botan_privkey_export_encrypted_pbkdf_msec(), and PEM_encode_encrypted_pbkdf_msec().

copy_key() [1/2]

std::unique_ptr< Private_Key > Botan::PKCS8::copy_key ( const Private_Key &  key )

inline

Copy an existing encoded key object.

Parameters

key	the key to copy

Returns

new copy of the key

Definition at line 214 of file pkcs8.h.

   {
   DataSource_Memory source(key.private_key_info());
   return PKCS8::load_key(source);
   }

References load_key().

Referenced by copy_key().

copy_key() [2/2]

Private_Key * Botan::PKCS8::copy_key ( const Private_Key &  key, RandomNumberGenerator &  rng  )

inline

Copy an existing encoded key object.

Parameters

key	the key to copy
rng	ignored for compatibility

Returns

new copy of the key

Definition at line 324 of file pkcs8.h.

   {
   BOTAN_UNUSED(rng);
   return PKCS8::copy_key(key).release();
   }

References BOTAN_UNUSED, and copy_key().

load_key() [1/6]

std::unique_ptr< Private_Key > Botan::PKCS8::load_key

(

DataSource &

source

)

Load an unencrypted key from a data source.

Parameters

source

the data source providing the encoded key

Returns

loaded private key object

Definition at line 375 of file pkcs8.cpp.

   {
   auto fail_fn = []() -> std::string {
      throw PKCS8_Exception("Internal error: Attempt to read password for unencrypted key");
   };
 
   return load_key(source, fail_fn, false);
   }

References load_key().

load_key() [2/6]

std::unique_ptr< Private_Key > Botan::PKCS8::load_key	(	DataSource &	source,
		const std::function< std::string()> &	get_passphrase
	)

Load an encrypted key from a data source.

Parameters

source	the data source providing the encoded key
get_passphrase	a function that returns passphrases

Returns

loaded private key object

Definition at line 355 of file pkcs8.cpp.

   {
   return load_key(source, get_pass, true);
   }

References load_key().

Referenced by botan_privkey_load(), copy_key(), Botan::Certificate_Store_In_SQL::find_key(), and load_key().

load_key() [3/6]

std::unique_ptr< Private_Key > Botan::PKCS8::load_key	(	DataSource &	source,
		const std::string &	pass
	)

Load an encrypted key from a data source.

Parameters

source	the data source providing the encoded key
pass	the passphrase to decrypt the key

Returns

loaded private key object

Definition at line 364 of file pkcs8.cpp.

   {
   // We need to use bind rather than a lambda capturing `pass` here in order to avoid a Clang 8 bug.
   // See https://github.com/randombit/botan/issues/2255.
   return load_key(source, std::bind([](const std::string& p) { return p; }, pass), true);
   }

References load_key().

load_key() [4/6]

Private_Key * Botan::PKCS8::load_key ( DataSource &  source, RandomNumberGenerator &  rng  )

inline

Load an unencrypted key from a data source.

Parameters

source	the data source providing the encoded key
rng	ignored for compatibility

Returns

loaded private key object

Definition at line 259 of file pkcs8.h.

   {
   BOTAN_UNUSED(rng);
   return PKCS8::load_key(source).release();
   }

References BOTAN_UNUSED, and load_key().

load_key() [5/6]

Private_Key * Botan::PKCS8::load_key ( DataSource &  source, RandomNumberGenerator &  rng, const std::string &  pass  )

inline

Load an encrypted key from a data source.

Parameters

source	the data source providing the encoded key
rng	ignored for compatibility
pass	the passphrase to decrypt the key

Returns

loaded private key object

Definition at line 245 of file pkcs8.h.

   {
   BOTAN_UNUSED(rng);
   return PKCS8::load_key(source, pass).release();
   }

References BOTAN_UNUSED, and load_key().

load_key() [6/6]

Private_Key * Botan::PKCS8::load_key ( DataSource &  source, RandomNumberGenerator &  rng, std::function< std::string()>  get_passphrase  )

inline

Load an encrypted key from a data source.

Parameters

source	the data source providing the encoded key
rng	ignored for compatibility
get_passphrase	a function that returns passphrases

Returns

loaded private key object

Definition at line 230 of file pkcs8.h.

   {
   BOTAN_UNUSED(rng);
   return PKCS8::load_key(source, get_passphrase).release();
   }

References BOTAN_UNUSED, and load_key().

PEM_encode() [1/2]

std::string Botan::PKCS8::PEM_encode

(

const Private_Key &

key

)

Get a string containing a PEM encoded private key.

Parameters

key	the key to encode

Returns

encoded key

Definition at line 137 of file pkcs8.cpp.

   {
   return PEM_Code::encode(key.private_key_info(), "PRIVATE KEY");
   }

References Botan::PEM_Code::encode(), and Botan::Private_Key::private_key_info().

Referenced by botan_privkey_export(), and PEM_encode().

PEM_encode() [2/2]

std::string Botan::PKCS8::PEM_encode	(	const Private_Key &	key,
		RandomNumberGenerator &	rng,
		const std::string &	pass,
		std::chrono::milliseconds	msec = std::chrono::milliseconds(300),
		const std::string &	pbe_algo = ""
	)

Get a string containing a PEM encoded private key, encrypting it with a password.

Parameters

key	the key to encode
rng	the rng to use
pass	the password to use for encryption
msec	number of milliseconds to run the password derivation
pbe_algo	the name of the desired password-based encryption algorithm; if empty ("") a reasonable (portable/secure) default will be chosen.

Returns

encrypted key in PEM form

Definition at line 219 of file pkcs8.cpp.

   {
   if(pass.empty())
      return PEM_encode(key);
 
   return PEM_Code::encode(PKCS8::BER_encode(key, rng, pass, msec, pbe_algo),
                           "ENCRYPTED PRIVATE KEY");
   }

References BER_encode(), Botan::PEM_Code::encode(), and PEM_encode().

PEM_encode_encrypted_pbkdf_iter()

std::string Botan::PKCS8::PEM_encode_encrypted_pbkdf_iter	(	const Private_Key &	key,
		RandomNumberGenerator &	rng,
		const std::string &	pass,
		size_t	pbkdf_iter,
		const std::string &	cipher = "",
		const std::string &	pbkdf_hash = ""
	)

Get a string containing a PEM encoded private key, encrypting it with a password.

Parameters

key	the key to encode
rng	the rng to use
pass	the password to use for encryption
pbkdf_iter	number of iterations to run PBKDF
cipher	if non-empty specifies the cipher to use. CBC and GCM modes are supported, for example "AES-128/CBC", "AES-256/GCM", "Serpent/CBC". If empty a suitable default is chosen.
pbkdf_hash	if non-empty specifies the PBKDF hash function to use. For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.

Returns

encrypted key in PEM form

Definition at line 268 of file pkcs8.cpp.

   {
   return PEM_Code::encode(
      PKCS8::BER_encode_encrypted_pbkdf_iter(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash),
      "ENCRYPTED PRIVATE KEY");
   }

References BER_encode_encrypted_pbkdf_iter(), and Botan::PEM_Code::encode().

Referenced by botan_privkey_export_encrypted_pbkdf_iter().

PEM_encode_encrypted_pbkdf_msec()

std::string Botan::PKCS8::PEM_encode_encrypted_pbkdf_msec	(	const Private_Key &	key,
		RandomNumberGenerator &	rng,
		const std::string &	pass,
		std::chrono::milliseconds	pbkdf_msec,
		size_t *	pbkdf_iterations,
		const std::string &	cipher = "",
		const std::string &	pbkdf_hash = ""
	)

Get a string containing a PEM encoded private key, encrypting it with a password.

Parameters

key	the key to encode
rng	the rng to use
pass	the password to use for encryption
pbkdf_msec	how long in milliseconds to run PBKDF2
pbkdf_iterations	(output argument) number of iterations of PBKDF that ended up being used
cipher	if non-empty specifies the cipher to use. CBC and GCM modes are supported, for example "AES-128/CBC", "AES-256/GCM", "Serpent/CBC". If empty a suitable default is chosen.
pbkdf_hash	if non-empty specifies the PBKDF hash function to use. For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.

Returns

encrypted key in PEM form

Definition at line 316 of file pkcs8.cpp.

   {
   return PEM_Code::encode(
      PKCS8::BER_encode_encrypted_pbkdf_msec(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash),
      "ENCRYPTED PRIVATE KEY");
   }

References BER_encode_encrypted_pbkdf_msec(), and Botan::PEM_Code::encode().

Referenced by botan_privkey_export_encrypted_pbkdf_msec().