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, std::string_view pass, std::chrono::milliseconds msec, std::string_view pbe_algo)
std::vector< uint8_t >	BER_encode_encrypted_pbkdf_iter (const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, size_t pbkdf_iterations, std::string_view cipher, std::string_view pbkdf_hash)
std::vector< uint8_t >	BER_encode_encrypted_pbkdf_msec (const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, std::chrono::milliseconds pbkdf_msec, size_t *pbkdf_iterations, std::string_view cipher, std::string_view pbkdf_hash)
std::unique_ptr< Private_Key >	copy_key (const Private_Key &key)
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, std::string_view pass)
std::unique_ptr< Private_Key >	load_key (std::span< const uint8_t > source)
std::unique_ptr< Private_Key >	load_key (std::span< const uint8_t > source, const std::function< std::string()> &get_passphrase)
std::unique_ptr< Private_Key >	load_key (std::span< const uint8_t > source, std::string_view pass)
std::string	PEM_encode (const Private_Key &key)
std::string	PEM_encode (const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, std::chrono::milliseconds msec, std::string_view pbe_algo)
std::string	PEM_encode_encrypted_pbkdf_iter (const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, size_t pbkdf_iterations, std::string_view cipher, std::string_view pbkdf_hash)
std::string	PEM_encode_encrypted_pbkdf_msec (const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, std::chrono::milliseconds pbkdf_msec, size_t *pbkdf_iterations, std::string_view cipher, std::string_view 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,
		std::string_view	pass,
		std::chrono::milliseconds	msec = std::chrono::milliseconds(300),
		std::string_view	pbe_algo = "" )

Encrypt a key using PKCS #8 encryption

Parameters

key	the key to encode
Random Number Generators	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 167 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::Asymmetric_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::PKCS12::export_to(), 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,
		std::string_view	pass,
		size_t	pbkdf_iter,
		std::string_view	cipher = "",
		std::string_view	pbkdf_hash = "" )

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

Parameters

key	the key to encode
Random Number Generators	the rng to use
pass	the password to use for encryption
pbkdf_iter	number of iterations 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 207 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_view_encrypted_der(), 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,
		std::string_view	pass,
		std::chrono::milliseconds	pbkdf_msec,
		size_t *	pbkdf_iterations,
		std::string_view	cipher = "",
		std::string_view	pbkdf_hash = "" )

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

Parameters

key	the key to encode
Random Number Generators	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 250 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_view_encrypted_der_timed(), and PEM_encode_encrypted_pbkdf_msec().

copy_key()

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 236 of file pkcs8.h.

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

References copy_key(), and load_key().

Referenced by 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 350 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 319 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(), load_key(), load_key(), load_key(), load_key(), load_key(), and load_key().

load_key() [3/6]

std::unique_ptr< Private_Key > Botan::PKCS8::load_key	(	DataSource &	source,
		std::string_view	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 342 of file pkcs8.cpp.

                                                                             {
   return load_key(
      source, [pass]() { return std::string(pass); }, true);
}

References load_key().

load_key() [4/6]

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

(

std::span< const uint8_t >

source

)

Load an unencrypted key from memory.

Parameters

source

the byte buffer containing the encoded key

Returns

loaded private key object

Definition at line 334 of file pkcs8.cpp.

                                                                   {
   Botan::DataSource_Memory ds(source);
   return load_key(ds);
}

References load_key().

load_key() [5/6]

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

Load an encrypted key from memory.

Parameters

source	the byte buffer containing the encoded key
get_passphrase	a function that returns passphrases

Returns

loaded private key object

Definition at line 323 of file pkcs8.cpp.

                                                                                      {
   Botan::DataSource_Memory ds(source);
   return load_key(ds, get_passphrase);
}

References load_key().

load_key() [6/6]

std::unique_ptr< Private_Key > Botan::PKCS8::load_key	(	std::span< const uint8_t >	source,
		std::string_view	pass )

Load an encrypted key from memory.

Parameters

source	the byte buffer containing the encoded key
pass	the passphrase to decrypt the key

Returns

loaded private key object

Definition at line 329 of file pkcs8.cpp.

                                                                                        {
   Botan::DataSource_Memory ds(source);
   return load_key(ds, pass);
}

References 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 122 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_view_pem(), and PEM_encode().

PEM_encode() [2/2]

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

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

Parameters

key	the key to encode
Random Number Generators	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 192 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,
		std::string_view	pass,
		size_t	pbkdf_iter,
		std::string_view	cipher = "",
		std::string_view	pbkdf_hash = "" )

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

Parameters

key	the key to encode
Random Number Generators	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 237 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_view_encrypted_pem().

PEM_encode_encrypted_pbkdf_msec()

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

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

Parameters

key	the key to encode
Random Number Generators	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 284 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_view_encrypted_pem_timed().