Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- Namespace List
- Namespace Members

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_Key * | copy_key (const Private_Key &key, RandomNumberGenerator &rng)
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

BOTAN_DLL 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 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

  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 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 }
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:169
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:134
Botan::OCTET_STRING
Definition: asn1_obj.h:35
Botan::SEQUENCE
Definition: asn1_obj.h:39

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

  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 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 }
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:153
Botan::OCTET_STRING
Definition: asn1_obj.h:35
Botan::SEQUENCE
Definition: asn1_obj.h:39

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

  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 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 }
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:134
Botan::OCTET_STRING
Definition: asn1_obj.h:35
Botan::SEQUENCE
Definition: asn1_obj.h:39

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 | ignored 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 }
Botan::PKCS8::load_key
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:333
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: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

  source | the data source providing the encoded key
  rng | ignored for compatability
  get_passphrase | a 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 }
Botan::PKCS8::load_key
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

  source | the data source providing the encoded key
  rng | ignored for compatability
  pass | the 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 }
Botan::PKCS8::load_key
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

  source | the data source providing the encoded key
  rng | ignored 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 }
Botan::PKCS8::load_key
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

  key | the 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 }
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
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: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

  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 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 }
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
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:169
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: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

  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 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 }
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:208
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

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

  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 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 }
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
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:248