Botan 2.19.5 Crypto and TLS for C&

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_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::unique_ptr< Private_Key > | load_key (DataSource &source, const std::string &pass)
Private_Key * | load_key (DataSource &source, RandomNumberGenerator &rng)
Private_Key * | load_key (DataSource &source, RandomNumberGenerator &rng, const std::string &pass)
Private_Key * | load_key (DataSource &source, RandomNumberGenerator &rng, std::function< std::string()> get_pass)
std::unique_ptr< Private_Key > | load_key (DataSource &source, std::function< std::string()> get_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)
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

  key | the private key to encode

Returns
  BER encoded key

Definition at line 139 of file pkcs8.cpp.

140 {
141 // keeping around for compat
142 return key.private_key_info();
143 }
Botan::Private_Key::private_key_info
secure_vector< uint8_t > private_key_info() const
Definition: pk_keys.cpp:61

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

## ◆ 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

  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.

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 }
BOTAN_UNUSED
#define BOTAN_UNUSED(...)
Definition: assert.h:142
Botan::DER_Encoder
Definition: der_enc.h:23
Botan::Encoding_Error
Definition: exceptn.h:185
Botan::Public_Key::algo_name
virtual std::string algo_name() const =0
Botan::PKCS8::BER_encode
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
Botan::pbes2_encrypt_msec
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:273
Botan::SEQUENCE
@ SEQUENCE
Definition: asn1_obj.h:42
Botan::OCTET_STRING
@ OCTET_STRING
Definition: asn1_obj.h:38

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

## ◆ 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

  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.

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 }
Botan::pbes2_encrypt_iter
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:292

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

## ◆ 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

  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.

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 }
Botan::DER_Encoder::start_cons
DER_Encoder & start_cons(ASN1_Tag type_tag, ASN1_Tag class_tag=UNIVERSAL)
Definition: der_enc.cpp:181
Botan::DER_Encoder::end_cons
DER_Encoder & end_cons()
Definition: der_enc.cpp:191
Botan::DER_Encoder::encode
DER_Encoder & encode(bool b)
Definition: der_enc.cpp:285

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

## ◆ copy_key() [1/2]

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

399 {
400 DataSource_Memory source(PEM_encode(key));
401 return PKCS8::load_key(source);
402 }
Botan::DataSource_Memory
Definition: data_src.h:99
Botan::PKCS8::PEM_encode
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
Botan::PKCS8::load_key
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:429

References load_key(), and PEM_encode().

Referenced by copy_key().

## ◆ copy_key() [2/2]

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

481 {
482 BOTAN_UNUSED(rng);
483 return PKCS8::copy_key(key).release();
484 }
Botan::PKCS8::copy_key
Private_Key * copy_key(const Private_Key &key, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:479

References BOTAN_UNUSED, and copy_key().

## ◆ load_key() [1/6]

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

387 {
388 auto fail_fn = []() -> std::string {
389 throw PKCS8_Exception("Internal error: Attempt to read password for unencrypted key");
390 };
391
392 return load_key(source, fail_fn, false);
393 }
Botan::PKCS8_Exception
Definition: pkcs8.h:27

References load_key().

## ◆ 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

  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.

377 {
378 // We need to use bind rather than a lambda capturing `pass` here in order to avoid a Clang 8 bug.
379 // See https://github.com/randombit/botan/issues/2255.
380 return load_key(source, std::bind([](const std::string p) { return p; }, pass), true);
381 }

References load_key().

## ◆ load_key() [3/6]

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

431 {
432 BOTAN_UNUSED(rng);
433 return PKCS8::load_key(source).release();
434 }

References BOTAN_UNUSED, and load_key().

## ◆ load_key() [4/6]

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

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

References BOTAN_UNUSED, and load_key().

## ◆ load_key() [5/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

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

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

References BOTAN_UNUSED, and load_key().

## ◆ load_key() [6/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

  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.

368 {
369 return load_key(source, get_pass, true);
370 }

References load_key().

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

## ◆ PEM_encode() [1/2]

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.

149 {
150 return PEM_Code::encode(PKCS8::BER_encode(key), "PRIVATE KEY");
151 }
Botan::PEM_Code::encode
std::string encode(const uint8_t der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:43

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

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

## ◆ 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

  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.

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 }

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

## ◆ 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

  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.

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 }
Botan::PKCS8::BER_encode_encrypted_pbkdf_iter
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

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

Referenced by botan_privkey_export_encrypted_pbkdf_iter().

## ◆ 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

  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.

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 }
Botan::PKCS8::BER_encode_encrypted_pbkdf_msec
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

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

Referenced by botan_privkey_export_encrypted_pbkdf_msec().