Functions
secure_vector< byte >	BER_encode (const Private_Key &key)
std::vector< byte >	BER_encode (const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, std::chrono::milliseconds msec, const std::string &pbe_algo)
Private_Key *	copy_key (const Private_Key &key, RandomNumberGenerator &rng)
Private_Key *	load_key (DataSource &source, RandomNumberGenerator &rng, std::function< std::string()> get_pass)
Private_Key *	load_key (const std::string &fsname, RandomNumberGenerator &rng, std::function< std::string()> get_pass)
Private_Key *	load_key (DataSource &source, RandomNumberGenerator &rng, const std::string &pass)
Private_Key *	load_key (const std::string &fsname, RandomNumberGenerator &rng, const std::string &pass)
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)

Detailed Description

This namespace contains functions for handling PKCS #8 private keys

Function Documentation

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

BER encode a private key

Parameters:

key	the private key to encode

Returns:: BER encoded key

Definition at line 110 of file pkcs8.cpp.

References Botan::PEM_Code::encode(), Botan::DER_Encoder::encode(), Botan::OCTET_STRING, Botan::Private_Key::pkcs8_algorithm_identifier(), Botan::Private_Key::pkcs8_private_key(), Botan::SEQUENCE, and Botan::DER_Encoder::start_cons().

Referenced by BER_encode(), botan_privkey_export(), botan_privkey_export_encrypted(), Botan::TLS::Session::DER_encode(), and PEM_encode().

   {
   const size_t PKCS8_VERSION = 0;

   return DER_Encoder()
         .start_cons(SEQUENCE)
            .encode(PKCS8_VERSION)
            .encode(key.pkcs8_algorithm_identifier())
            .encode(key.pkcs8_private_key(), OCTET_STRING)
         .end_cons()
      .get_contents();
   }

BOTAN_DLL std::vector< byte > 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 156 of file pkcs8.cpp.

References Botan::Public_Key::algo_name(), BER_encode(), Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::DER_Encoder::get_contents_unlocked(), Botan::OCTET_STRING, Botan::pbes2_encrypt(), Botan::SEQUENCE, and Botan::DER_Encoder::start_cons().

   {
   const auto pbe_params = choose_pbe_params(pbe_algo, key.algo_name());

   const std::pair<AlgorithmIdentifier, std::vector<byte>> pbe_info =
      pbes2_encrypt(PKCS8::BER_encode(key), pass, msec,
                    pbe_params.first, pbe_params.second, rng);

   return DER_Encoder()
         .start_cons(SEQUENCE)
            .encode(pbe_info.first)
            .encode(pbe_info.second, OCTET_STRING)
         .end_cons()
      .get_contents_unlocked();
   }

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

Copy an existing encoded key object.

Parameters:

key	the key to copy
rng	the rng to use

Returns:: new copy of the key

Definition at line 244 of file pkcs8.cpp.

References load_key(), and PEM_encode().

   {
   DataSource_Memory source(PEM_encode(key));
   return PKCS8::load_key(source, rng);
   }

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

Load a key from a data source.

Parameters:

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

Returns:: loaded private key object

Definition at line 195 of file pkcs8.cpp.

References Botan::OID::as_string(), Botan::OIDS::lookup(), Botan::make_private_key(), and Botan::AlgorithmIdentifier::oid.

Referenced by botan_privkey_load(), copy_key(), load_key(), Botan::X509_Certificate::subject_public_key(), and Botan::PKCS10_Request::subject_public_key().

   {
   AlgorithmIdentifier alg_id;
   secure_vector<byte> pkcs8_key = PKCS8_decode(source, get_pass, alg_id);

   const std::string alg_name = OIDS::lookup(alg_id.oid);
   if(alg_name == "" || alg_name == alg_id.oid.as_string())
      throw PKCS8_Exception("Unknown algorithm OID: " +
                            alg_id.oid.as_string());

   return make_private_key(alg_id, pkcs8_key, rng);
   }

BOTAN_DLL Private_Key * Botan::PKCS8::load_key	(	const std::string &	filename,
		RandomNumberGenerator &	rng,
		std::function< std::string()>	get_passphrase
	)

Load a key from a file.

Parameters:

filename	the path to the file containing the encoded key
rng	the rng to use
get_passphrase	a function that returns passphrases

Returns:: loaded private key object

Definition at line 213 of file pkcs8.cpp.

References load_key().

   {
   DataSource_Stream source(fsname, true);
   return PKCS8::load_key(source, rng, get_pass);
   }

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

Load a key from a data source.

Parameters:

source	the data source providing the encoded key
rng	the rng to use
pass	the passphrase to decrypt the key. Provide an empty string if the key is not encrypted

Returns:: loaded private key object

Definition at line 224 of file pkcs8.cpp.

References load_key().

   {
   return PKCS8::load_key(source, rng, [pass]() { return pass; });
   }

BOTAN_DLL Private_Key * Botan::PKCS8::load_key	(	const std::string &	filename,
		RandomNumberGenerator &	rng,
		const std::string &	pass = `""`
	)

Load a key from a file.

Parameters:

filename	the path to the file containing the encoded key
rng	the rng to use
pass	the passphrase to decrypt the key. Provide an empty string if the key is not encrypted

Returns:: loaded private key object

Definition at line 234 of file pkcs8.cpp.

References load_key().

   {
   return PKCS8::load_key(fsname, rng, [pass]() { return pass; });
   }

BOTAN_DLL 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 126 of file pkcs8.cpp.

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

Referenced by botan_privkey_export(), botan_privkey_export_encrypted(), copy_key(), and PEM_encode().

   {
   return PEM_Code::encode(PKCS8::BER_encode(key), "PRIVATE KEY");
   }

BOTAN_DLL 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 179 of file pkcs8.cpp.

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

   {
   if(pass == "")
      return PEM_encode(key);

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

Functions

Detailed Description

Function Documentation