Botan::PKCS8 Namespace Reference

Functions
SecureVector< byte >	BER_encode (const Private_Key &key)
SecureVector< byte >	BER_encode (const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo)
Private_Key *	copy_key (const Private_Key &key, RandomNumberGenerator &rng)
void	encode (const Private_Key &key, Pipe &pipe, X509_Encoding encoding=PEM)
void	encrypt_key (const Private_Key &key, Pipe &pipe, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo="", X509_Encoding encoding=PEM)
Private_Key *	load_key (const std::string &fsname, RandomNumberGenerator &rng, const std::string &pass)
Private_Key *	load_key (const std::string &fsname, RandomNumberGenerator &rng, const User_Interface &ui)
Private_Key *	load_key (DataSource &source, RandomNumberGenerator &rng, const std::string &pass)
Private_Key *	load_key (DataSource &source, RandomNumberGenerator &rng, const User_Interface &ui)
std::string	PEM_encode (const Private_Key &key)
std::string	PEM_encode (const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, const std::string &pbe_algo)

Detailed Description

This namespace contains functions for handling PKCS #8 private keys

Function Documentation

BER_encode() [1/2]

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

   {
   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();
   }

References BER_encode(), Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::DER_Encoder::get_contents(), 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(), BER_encode(), encode(), encrypt_key(), PEM_encode(), and PEM_encode().

BER_encode() [2/2]

BOTAN_DLL SecureVector< byte > Botan::PKCS8::BER_encode	(	const Private_Key &	key,
		RandomNumberGenerator &	rng,
		const std::string &	pass,
		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
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 158 of file pkcs8.cpp.

   {
   const std::string DEFAULT_PBE = "PBE-PKCS5v20(SHA-1,AES-256/CBC)";
 
   std::auto_ptr<PBE> pbe(get_pbe(((pbe_algo != "") ? pbe_algo : DEFAULT_PBE)));
 
   pbe->new_params(rng);
   pbe->set_key(pass);
 
   AlgorithmIdentifier pbe_algid(pbe->get_oid(), pbe->encode_params());
 
   Pipe key_encrytor(pbe.release());
   key_encrytor.process_msg(PKCS8::BER_encode(key));
 
   return DER_Encoder()
         .start_cons(SEQUENCE)
            .encode(pbe_algid)
            .encode(key_encrytor.read_all(), OCTET_STRING)
         .end_cons()
      .get_contents();
   }

References BER_encode(), Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::DER_Encoder::get_contents(), Botan::get_pbe(), Botan::OCTET_STRING, Botan::Pipe::process_msg(), Botan::Pipe::read_all(), Botan::SEQUENCE, and Botan::DER_Encoder::start_cons().

copy_key()

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

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

References copy_key(), load_key(), and PEM_encode().

Referenced by copy_key(), and Botan::TLS_Server::TLS_Server().

encode()

void Botan::PKCS8::encode ( const Private_Key & key, Pipe & pipe, X509_Encoding encoding = PEM )

inline

Encode a private key into a pipe.

Deprecated

Use PEM_encode or BER_encode instead

Parameters

key	the private key to encode
pipe	the pipe to feed the encoded key into
encoding	the encoding type to use

Definition at line 85 of file pkcs8.h.

   {
   if(encoding == PEM)
      pipe.write(PKCS8::PEM_encode(key));
   else
      pipe.write(PKCS8::BER_encode(key));
   }

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

Referenced by encode().

encrypt_key()

void Botan::PKCS8::encrypt_key ( const Private_Key & key, Pipe & pipe, RandomNumberGenerator & rng, const std::string & pass, const std::string & pbe_algo = "", X509_Encoding encoding = PEM )

inline

Encode and encrypt a private key into a pipe.

Deprecated

Use PEM_encode or BER_encode instead

Parameters

key	the private key to encode
pipe	the pipe to feed the encoded key into
pass	the password to use for encryption
rng	the rng to use
pbe_algo	the name of the desired password-based encryption algorithm; if empty ("") a reasonable (portable/secure) default will be chosen.
encoding	the encoding type to use

Definition at line 109 of file pkcs8.h.

   {
   if(encoding == PEM)
      pipe.write(PKCS8::PEM_encode(key, rng, pass, pbe_algo));
   else
      pipe.write(PKCS8::BER_encode(key, rng, pass, pbe_algo));
   }

References BER_encode(), encrypt_key(), Botan::PEM, and PEM_encode().

Referenced by encrypt_key().

load_key() [1/4]

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 encoded.

Returns

loaded private key object

Definition at line 240 of file pkcs8.cpp.

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

References load_key(), and Botan::User_Interface::User_Interface().

load_key() [2/4]

BOTAN_DLL Private_Key * Botan::PKCS8::load_key	(	const std::string &	filename,
		RandomNumberGenerator &	rng,
		const User_Interface &	ui )

Load a key from a file.

Parameters

filename	the path to the file containing the encoded key
rng	the rng to use
ui	the user interface to be used for passphrase dialog

Returns

loaded private key object

Definition at line 219 of file pkcs8.cpp.

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

References load_key().

load_key() [3/4]

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 encoded.

Returns

loaded private key object

Definition at line 230 of file pkcs8.cpp.

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

References load_key(), and Botan::User_Interface::User_Interface().

load_key() [4/4]

BOTAN_DLL Private_Key * Botan::PKCS8::load_key	(	DataSource &	source,
		RandomNumberGenerator &	rng,
		const User_Interface &	ui )

Load a key from a data source.

Parameters

source	the data source providing the encoded key
rng	the rng to use
ui	the user interface to be used for passphrase dialog

Returns

loaded private key object

Definition at line 201 of file pkcs8.cpp.

   {
   AlgorithmIdentifier alg_id;
   SecureVector<byte> pkcs8_key = PKCS8_decode(source, ui, 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);
   }

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

Referenced by copy_key(), load_key(), load_key(), load_key(), and load_key().

PEM_encode() [1/2]

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

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

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

Referenced by copy_key(), encode(), encrypt_key(), PEM_encode(), and PEM_encode().

PEM_encode() [2/2]

BOTAN_DLL std::string Botan::PKCS8::PEM_encode	(	const Private_Key &	key,
		RandomNumberGenerator &	rng,
		const std::string &	pass,
		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
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 186 of file pkcs8.cpp.

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

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