Botan  2.1.0
Crypto and TLS for C++11
Functions
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)
 
Private_Keycopy_key (const Private_Key &key, RandomNumberGenerator &rng)
 
Private_Keyload_key (DataSource &source, RandomNumberGenerator &rng, std::function< std::string()> get_pass)
 
Private_Keyload_key (DataSource &source, RandomNumberGenerator &rng, const std::string &pass)
 
Private_Keyload_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

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

BER encode a private key

Parameters
keythe private key to encode
Returns
BER encoded key

Definition at line 130 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().

131  {
132  // keeping around for compat
133  return key.private_key_info();
134  }
BOTAN_DLL 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
keythe key to encode
rngthe rng to use
passthe password to use for encryption
msecnumber of milliseconds to run the password derivation
pbe_algothe 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 169 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_msec(), Botan::SEQUENCE, and Botan::DER_Encoder::start_cons().

174  {
175  const auto pbe_params = choose_pbe_params(pbe_algo, key.algo_name());
176 
177  const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
178  pbes2_encrypt_msec(PKCS8::BER_encode(key), pass, msec, nullptr,
179  pbe_params.first, pbe_params.second, rng);
180 
181  return DER_Encoder()
182  .start_cons(SEQUENCE)
183  .encode(pbe_info.first)
184  .encode(pbe_info.second, OCTET_STRING)
185  .end_cons()
186  .get_contents_unlocked();
187  }
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)
Definition: pkcs8.cpp:169
std::pair< AlgorithmIdentifier, std::vector< uint8_t > > pbes2_encrypt_msec(const secure_vector< uint8_t > &key_bits, const std::string &passphrase, std::chrono::milliseconds msec, size_t *out_iterations_if_nonnull, const std::string &cipher, const std::string &digest, RandomNumberGenerator &rng)
Definition: pbes2.cpp:134
BOTAN_DLL 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
keythe key to encode
rngthe rng to use
passthe password to use for encryption
pbkdf_iternumber of interations to run PBKDF2
cipherif 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_hashif 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 208 of file pkcs8.cpp.

References Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::DER_Encoder::get_contents_unlocked(), 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().

214  {
215  const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
216  pbes2_encrypt_iter(key.private_key_info(),
217  pass, pbkdf_iterations,
218  cipher.empty() ? "AES-256/CBC" : cipher,
219  pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
220  rng);
221 
222  return DER_Encoder()
223  .start_cons(SEQUENCE)
224  .encode(pbe_info.first)
225  .encode(pbe_info.second, OCTET_STRING)
226  .end_cons()
227  .get_contents_unlocked();
228  }
std::pair< AlgorithmIdentifier, std::vector< uint8_t > > pbes2_encrypt_iter(const secure_vector< uint8_t > &key_bits, const std::string &passphrase, size_t pbkdf_iter, const std::string &cipher, const std::string &digest, RandomNumberGenerator &rng)
Definition: pbes2.cpp:153
BOTAN_DLL 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
keythe key to encode
rngthe rng to use
passthe password to use for encryption
pbkdf_msechow long to run PBKDF2
pbkdf_iterationsif non-null, set to the number of iterations used
cipherif 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_hashif 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 248 of file pkcs8.cpp.

References Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::DER_Encoder::get_contents_unlocked(), 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().

255  {
256  const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
257  pbes2_encrypt_msec(key.private_key_info(), pass,
258  pbkdf_msec, pbkdf_iterations,
259  cipher.empty() ? "AES-256/CBC" : cipher,
260  pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
261  rng);
262 
263  return DER_Encoder()
264  .start_cons(SEQUENCE)
265  .encode(pbe_info.first)
266  .encode(pbe_info.second, OCTET_STRING)
267  .end_cons()
268  .get_contents_unlocked();
269  }
std::pair< AlgorithmIdentifier, std::vector< uint8_t > > pbes2_encrypt_msec(const secure_vector< uint8_t > &key_bits, const std::string &passphrase, std::chrono::milliseconds msec, size_t *out_iterations_if_nonnull, const std::string &cipher, const std::string &digest, RandomNumberGenerator &rng)
Definition: pbes2.cpp:134
BOTAN_DLL Private_Key * Botan::PKCS8::copy_key ( const Private_Key key,
RandomNumberGenerator rng 
)

Copy an existing encoded key object.

Parameters
keythe key to copy
rngignored for compatability
Returns
new copy of the key

Definition at line 378 of file pkcs8.cpp.

References load_key(), and PEM_encode().

380  {
381  DataSource_Memory source(PEM_encode(key));
382  return PKCS8::load_key(source, rng);
383  }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:333
std::string PEM_encode(const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, std::chrono::milliseconds msec, const std::string &pbe_algo)
Definition: pkcs8.cpp:192
BOTAN_DLL 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
sourcethe data source providing the encoded key
rngignored for compatability
get_passphrasea function that returns passphrases
Returns
loaded private key object

Definition at line 313 of file pkcs8.cpp.

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

316  {
317  return load_key(source, rng, get_pass, true);
318  }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:333
BOTAN_DLL Private_Key * Botan::PKCS8::load_key ( DataSource source,
RandomNumberGenerator rng,
const std::string &  pass 
)

Load an encrypted key from a data source.

Parameters
sourcethe data source providing the encoded key
rngignored for compatability
passthe passphrase to decrypt the key
Returns
loaded private key object

Definition at line 323 of file pkcs8.cpp.

References load_key().

326  {
327  return load_key(source, rng, [pass]() { return pass; }, true);
328  }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:333
BOTAN_DLL Private_Key * Botan::PKCS8::load_key ( DataSource source,
RandomNumberGenerator rng 
)

Load an unencrypted key from a data source.

Parameters
sourcethe data source providing the encoded key
rngignored for compatability
Returns
loaded private key object

Definition at line 333 of file pkcs8.cpp.

References load_key().

335  {
336  return load_key(source, rng, []() -> std::string {
337  throw PKCS8_Exception( "Internal error: Attempt to read password for unencrypted key" );}, false);
338  }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:333
BOTAN_DLL std::string Botan::PKCS8::PEM_encode ( const Private_Key key)

Get a string containing a PEM encoded private key.

Parameters
keythe key to encode
Returns
encoded key

Definition at line 139 of file pkcs8.cpp.

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

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

140  {
141  return PEM_Code::encode(PKCS8::BER_encode(key), "PRIVATE KEY");
142  }
std::string encode(const uint8_t der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:43
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)
Definition: pkcs8.cpp:169
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
keythe key to encode
rngthe rng to use
passthe password to use for encryption
msecnumber of milliseconds to run the password derivation
pbe_algothe 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.

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

197  {
198  if(pass.empty())
199  return PEM_encode(key);
200 
201  return PEM_Code::encode(PKCS8::BER_encode(key, rng, pass, msec, pbe_algo),
202  "ENCRYPTED PRIVATE KEY");
203  }
std::string encode(const uint8_t der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:43
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)
Definition: pkcs8.cpp:169
std::string PEM_encode(const Private_Key &key, RandomNumberGenerator &rng, const std::string &pass, std::chrono::milliseconds msec, const std::string &pbe_algo)
Definition: pkcs8.cpp:192
BOTAN_DLL 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
keythe key to encode
rngthe rng to use
passthe password to use for encryption
pbkdf_iternumber of iterations to run PBKDF
cipherif 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_hashif 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 233 of file pkcs8.cpp.

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

Referenced by botan_privkey_export_encrypted_pbkdf_iter().

239  {
240  return PEM_Code::encode(
241  PKCS8::BER_encode_encrypted_pbkdf_iter(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash),
242  "ENCRYPTED PRIVATE KEY");
243  }
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)
Definition: pkcs8.cpp:208
std::string encode(const uint8_t der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:43
BOTAN_DLL 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
keythe key to encode
rngthe rng to use
passthe password to use for encryption
pbkdf_msechow long in milliseconds to run PBKDF2
pbkdf_iterations(output argument) number of iterations of PBKDF that ended up being used
cipherif 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_hashif 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 274 of file pkcs8.cpp.

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

Referenced by botan_privkey_export_encrypted_pbkdf_msec().

281  {
282  return PEM_Code::encode(
283  PKCS8::BER_encode_encrypted_pbkdf_msec(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash),
284  "ENCRYPTED PRIVATE KEY");
285  }
std::string encode(const uint8_t der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:43
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)
Definition: pkcs8.cpp:248