Botan  2.12.1
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)
 
std::unique_ptr< Private_Keycopy_key (const Private_Key &key)
 
Private_Keycopy_key (const Private_Key &key, RandomNumberGenerator &rng)
 
std::unique_ptr< Private_Keyload_key (DataSource &source, std::function< std::string()> get_pass)
 
std::unique_ptr< Private_Keyload_key (DataSource &source, const std::string &pass)
 
std::unique_ptr< Private_Keyload_key (DataSource &source)
 
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

◆ BER_encode() [1/2]

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 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().

140  {
141  // keeping around for compat
142  return key.private_key_info();
143  }

◆ BER_encode() [2/2]

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 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().

205  {
206 #if defined(BOTAN_HAS_PKCS5_PBES2)
207  const auto pbe_params = choose_pbe_params(pbe_algo, key.algo_name());
208 
209  const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
210  pbes2_encrypt_msec(PKCS8::BER_encode(key), pass, msec, nullptr,
211  pbe_params.first, pbe_params.second, rng);
212 
213  std::vector<uint8_t> output;
214  DER_Encoder der(output);
215  der.start_cons(SEQUENCE)
216  .encode(pbe_info.first)
217  .encode(pbe_info.second, OCTET_STRING)
218  .end_cons();
219 
220  return output;
221 #else
222  BOTAN_UNUSED(key, rng, pass, msec, pbe_algo);
223  throw Encoding_Error("PKCS8::BER_encode cannot encrypt because PBES2 was disabled in build");
224 #endif
225  }
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:276
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:200
#define BOTAN_UNUSED(...)
Definition: assert.h:142

◆ BER_encode_encrypted_pbkdf_iter()

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 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().

252  {
253 #if defined(BOTAN_HAS_PKCS5_PBES2)
254  const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
255  pbes2_encrypt_iter(key.private_key_info(),
256  pass, pbkdf_iterations,
257  cipher.empty() ? "AES-256/CBC" : cipher,
258  pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
259  rng);
260 
261  std::vector<uint8_t> output;
262  DER_Encoder der(output);
263  der.start_cons(SEQUENCE)
264  .encode(pbe_info.first)
265  .encode(pbe_info.second, OCTET_STRING)
266  .end_cons();
267 
268  return output;
269 
270 #else
271  BOTAN_UNUSED(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash);
272  throw Encoding_Error("PKCS8::BER_encode_encrypted_pbkdf_iter cannot encrypt because PBES2 disabled in build");
273 #endif
274  }
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:295
#define BOTAN_UNUSED(...)
Definition: assert.h:142

◆ BER_encode_encrypted_pbkdf_msec()

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 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().

301  {
302 #if defined(BOTAN_HAS_PKCS5_PBES2)
303  const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
304  pbes2_encrypt_msec(key.private_key_info(), pass,
305  pbkdf_msec, pbkdf_iterations,
306  cipher.empty() ? "AES-256/CBC" : cipher,
307  pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
308  rng);
309 
310  std::vector<uint8_t> output;
311  DER_Encoder(output)
312  .start_cons(SEQUENCE)
313  .encode(pbe_info.first)
314  .encode(pbe_info.second, OCTET_STRING)
315  .end_cons();
316 
317  return output;
318 #else
319  BOTAN_UNUSED(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash);
320  throw Encoding_Error("BER_encode_encrypted_pbkdf_msec cannot encrypt because PBES2 disabled in build");
321 #endif
322  }
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:276
#define BOTAN_UNUSED(...)
Definition: assert.h:142

◆ copy_key() [1/2]

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

Copy an existing encoded key object.

Parameters
keythe 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().

397  {
398  DataSource_Memory source(PEM_encode(key));
399  return PKCS8::load_key(source);
400  }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:427
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:230

◆ copy_key() [2/2]

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 compatibility
Returns
new copy of the key

Definition at line 475 of file pkcs8.cpp.

References BOTAN_UNUSED, and copy_key().

477  {
478  BOTAN_UNUSED(rng);
479  return PKCS8::copy_key(key).release();
480  }
Private_Key * copy_key(const Private_Key &key, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:475
#define BOTAN_UNUSED(...)
Definition: assert.h:142

◆ load_key() [1/6]

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
sourcethe data source providing the encoded key
get_passphrasea 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().

368  {
369  return load_key(source, get_pass, true);
370  }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:427

◆ load_key() [2/6]

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

Load an encrypted key from a data source.

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

Definition at line 375 of file pkcs8.cpp.

References load_key().

377  {
378  return load_key(source, [pass]() { return pass; }, true);
379  }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:427

◆ load_key() [3/6]

std::unique_ptr< Private_Key > Botan::PKCS8::load_key ( DataSource source)

Load an unencrypted key from a data source.

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

Definition at line 384 of file pkcs8.cpp.

References load_key().

385  {
386  auto fail_fn = []() -> std::string {
387  throw PKCS8_Exception("Internal error: Attempt to read password for unencrypted key");
388  };
389 
390  return load_key(source, fail_fn, false);
391  }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:427

◆ load_key() [4/6]

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 compatibility
get_passphrasea function that returns passphrases
Returns
loaded private key object

Definition at line 405 of file pkcs8.cpp.

References BOTAN_UNUSED, and load_key().

408  {
409  BOTAN_UNUSED(rng);
410  return PKCS8::load_key(source, get_pass).release();
411  }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:427
#define BOTAN_UNUSED(...)
Definition: assert.h:142

◆ load_key() [5/6]

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 compatibility
passthe passphrase to decrypt the key
Returns
loaded private key object

Definition at line 416 of file pkcs8.cpp.

References BOTAN_UNUSED, and load_key().

419  {
420  BOTAN_UNUSED(rng);
421  return PKCS8::load_key(source, pass).release();
422  }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:427
#define BOTAN_UNUSED(...)
Definition: assert.h:142

◆ load_key() [6/6]

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 compatibility
Returns
loaded private key object

Definition at line 427 of file pkcs8.cpp.

References BOTAN_UNUSED, and load_key().

429  {
430  BOTAN_UNUSED(rng);
431  return PKCS8::load_key(source).release();
432  }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:427
#define BOTAN_UNUSED(...)
Definition: assert.h:142

◆ PEM_encode() [1/2]

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

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

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

149  {
150  return PEM_Code::encode(PKCS8::BER_encode(key), "PRIVATE KEY");
151  }
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:200

◆ PEM_encode() [2/2]

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

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

235  {
236  if(pass.empty())
237  return PEM_encode(key);
238 
239  return PEM_Code::encode(PKCS8::BER_encode(key, rng, pass, msec, pbe_algo),
240  "ENCRYPTED PRIVATE KEY");
241  }
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:200
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:230

◆ PEM_encode_encrypted_pbkdf_iter()

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

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

Referenced by botan_privkey_export_encrypted_pbkdf_iter().

285  {
286  return PEM_Code::encode(
287  PKCS8::BER_encode_encrypted_pbkdf_iter(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash),
288  "ENCRYPTED PRIVATE KEY");
289  }
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:246
std::string encode(const uint8_t der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:43

◆ PEM_encode_encrypted_pbkdf_msec()

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

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

Referenced by botan_privkey_export_encrypted_pbkdf_msec().

334  {
335  return PEM_Code::encode(
336  PKCS8::BER_encode_encrypted_pbkdf_msec(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash),
337  "ENCRYPTED PRIVATE KEY");
338  }
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:294
std::string encode(const uint8_t der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:43