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::function< std::string()> get_pass)

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

std::unique_ptr< Private_Key >	load_key (DataSource &source)

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

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

Private_Key *	load_key (DataSource &source, RandomNumberGenerator &rng)

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

secure_vector< uint8_t > 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 139 of file pkcs8.cpp.

References Botan::Private_Key::private_key_info().

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

    {
    // keeping around for compat
    return key.private_key_info();
    }

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

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

    {
 #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_cons(SEQUENCE)
          .encode(pbe_info.first)
          .encode(pbe_info.second, OCTET_STRING)
       .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
    }

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

References BOTAN_UNUSED, Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::OCTET_STRING, Botan::pbes2_encrypt_iter(), Botan::Private_Key::private_key_info(), Botan::SEQUENCE, and Botan::DER_Encoder::start_cons().

Referenced by botan_privkey_export_encrypted_pbkdf_iter(), and PEM_encode_encrypted_pbkdf_iter().

    {
 #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_cons(SEQUENCE)
          .encode(pbe_info.first)
          .encode(pbe_info.second, OCTET_STRING)
       .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
    }

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

References BOTAN_UNUSED, Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::OCTET_STRING, Botan::pbes2_encrypt_msec(), Botan::Private_Key::private_key_info(), Botan::SEQUENCE, and Botan::DER_Encoder::start_cons().

Referenced by botan_privkey_export_encrypted_pbkdf_msec(), and PEM_encode_encrypted_pbkdf_msec().

    {
 #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_cons(SEQUENCE)
          .encode(pbe_info.first)
          .encode(pbe_info.second, OCTET_STRING)
       .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
    }

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

Copy an existing encoded key object.

Parameters

key	the key to copy

Returns: new copy of the key

Definition at line 396 of file pkcs8.cpp.

References load_key(), and PEM_encode().

Referenced by copy_key().

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

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	ignored for compatibility

Returns: new copy of the key

Definition at line 475 of file pkcs8.cpp.

References BOTAN_UNUSED, and copy_key().

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

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

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

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

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

References load_key().

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

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

References load_key().

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

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

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

References BOTAN_UNUSED, and load_key().

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

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

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

References BOTAN_UNUSED, and load_key().

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

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

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

References BOTAN_UNUSED, and load_key().

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

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

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

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

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

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

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

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

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

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

Referenced by botan_privkey_export_encrypted_pbkdf_iter().

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

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

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

Referenced by botan_privkey_export_encrypted_pbkdf_msec().

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

Functions

Detailed Description

Function Documentation