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

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 }
#define BOTAN_UNUSED(...)
Definition: assert.h:142
virtual std::string algo_name() const =0
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::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
@ SEQUENCE
Definition: asn1_obj.h:42
@ 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
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.

252 {
253#if defined(BOTAN_HAS_PKCS5_PBES2)
254 const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_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: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
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.

301 {
302#if defined(BOTAN_HAS_PKCS5_PBES2)
303 const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
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)
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 }
DER_Encoder & start_cons(ASN1_Tag type_tag, ASN1_Tag class_tag=UNIVERSAL)
Definition: der_enc.cpp:181
DER_Encoder & end_cons()
Definition: der_enc.cpp:191
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
keythe 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 }
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
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
keythe key to copy
rngignored 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 }
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
sourcethe 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 }

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

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
sourcethe data source providing the encoded key
rngignored 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
sourcethe data source providing the encoded key
rngignored for compatibility
passthe 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
sourcethe data source providing the encoded key
rngignored for compatibility
get_passphrasea 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
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.

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
keythe 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 }
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
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.

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

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

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

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

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

Referenced by botan_privkey_export_encrypted_pbkdf_msec().