Botan 3.14.1
Crypto and TLS for C&
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, std::string_view pass, std::chrono::milliseconds msec, std::string_view pbe_algo)
std::vector< uint8_t > BER_encode_encrypted_pbkdf_iter (const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, size_t pbkdf_iterations, std::string_view cipher, std::string_view pbkdf_hash)
std::vector< uint8_t > BER_encode_encrypted_pbkdf_msec (const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, std::chrono::milliseconds pbkdf_msec, size_t *pbkdf_iterations, std::string_view cipher, std::string_view pbkdf_hash)
std::unique_ptr< Private_Key > copy_key (const Private_Key &key)
std::unique_ptr< Private_Key > load_key (DataSource &source)
std::unique_ptr< Private_Key > load_key (DataSource &source, const std::function< std::string()> &get_pass)
std::unique_ptr< Private_Key > load_key (DataSource &source, std::string_view pass)
std::unique_ptr< Private_Key > load_key (std::span< const uint8_t > source)
std::unique_ptr< Private_Key > load_key (std::span< const uint8_t > source, const std::function< std::string()> &get_passphrase)
std::unique_ptr< Private_Key > load_key (std::span< const uint8_t > source, std::string_view pass)
std::string PEM_encode (const Private_Key &key)
std::string PEM_encode (const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, std::chrono::milliseconds msec, std::string_view pbe_algo)
std::string PEM_encode_encrypted_pbkdf_iter (const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, size_t pbkdf_iterations, std::string_view cipher, std::string_view pbkdf_hash)
std::string PEM_encode_encrypted_pbkdf_msec (const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, std::chrono::milliseconds pbkdf_msec, size_t *pbkdf_iterations, std::string_view cipher, std::string_view 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)
inline

BER encode a private key

Parameters
keythe private key to encode
Returns
BER encoded key

Definition at line 43 of file pkcs8.h.

43 {
44 return key.private_key_info();
45}
secure_vector< uint8_t > private_key_info() const
Definition pk_keys.cpp:77

References Botan::Private_Key::private_key_info().

◆ BER_encode() [2/2]

std::vector< uint8_t > Botan::PKCS8::BER_encode ( const Private_Key & key,
RandomNumberGenerator & rng,
std::string_view pass,
std::chrono::milliseconds msec = std::chrono::milliseconds(300),
std::string_view pbe_algo = "" )

Encrypt a key using PKCS #8 encryption

Parameters
keythe key to encode
Random Number Generatorsthe 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 168 of file pkcs8.cpp.

172 {
173#if defined(BOTAN_HAS_PKCS5_PBES2)
174 const auto pbe_params = choose_pbe_params(pbe_algo, key.algo_name());
175
176 const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
177 pbes2_encrypt_msec(PKCS8::BER_encode(key), pass, msec, nullptr, pbe_params.first, pbe_params.second, rng);
178
179 std::vector<uint8_t> output;
180 DER_Encoder der(output);
181 der.start_sequence().encode(pbe_info.first).encode(pbe_info.second, ASN1_Type::OctetString).end_cons();
182
183 return output;
184#else
185 BOTAN_UNUSED(key, rng, pass, msec, pbe_algo);
186 throw Encoding_Error("PKCS8::BER_encode cannot encrypt because PBES2 was disabled in build");
187#endif
188}
#define BOTAN_UNUSED
Definition assert.h:151
virtual std::string algo_name() const =0
std::vector< uint8_t > BER_encode(const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, std::chrono::milliseconds msec, std::string_view pbe_algo)
Definition pkcs8.cpp:168
std::pair< AlgorithmIdentifier, std::vector< uint8_t > > pbes2_encrypt_msec(std::span< const uint8_t > key_bits, std::string_view passphrase, std::chrono::milliseconds msec, size_t *out_iterations_if_nonnull, std::string_view cipher, std::string_view digest, RandomNumberGenerator &rng)
Definition pbes2.cpp:396

References Botan::Asymmetric_Key::algo_name(), BER_encode(), BOTAN_UNUSED, Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::OctetString, Botan::pbes2_encrypt_msec(), and Botan::DER_Encoder::start_sequence().

Referenced by BER_encode(), Botan::PKCS12::export_to(), Botan::Certificate_Store_In_SQL::insert_key(), and PEM_encode().

◆ BER_encode_encrypted_pbkdf_iter()

std::vector< uint8_t > Botan::PKCS8::BER_encode_encrypted_pbkdf_iter ( const Private_Key & key,
RandomNumberGenerator & rng,
std::string_view pass,
size_t pbkdf_iter,
std::string_view cipher = "",
std::string_view pbkdf_hash = "" )

Encrypt a key using PKCS #8 encryption and a fixed iteration count

Parameters
keythe key to encode
Random Number Generatorsthe rng to use
passthe password to use for encryption
pbkdf_iternumber of iterations 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.

213 {
214#if defined(BOTAN_HAS_PKCS5_PBES2)
215 const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
217 pass,
218 pbkdf_iterations,
219 cipher.empty() ? "AES-256/CBC" : cipher,
220 pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
221 rng);
222
223 std::vector<uint8_t> output;
224 DER_Encoder der(output);
225 der.start_sequence().encode(pbe_info.first).encode(pbe_info.second, ASN1_Type::OctetString).end_cons();
226
227 return output;
228
229#else
230 BOTAN_UNUSED(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash);
231 throw Encoding_Error("PKCS8::BER_encode_encrypted_pbkdf_iter cannot encrypt because PBES2 disabled in build");
232#endif
233}
std::pair< AlgorithmIdentifier, std::vector< uint8_t > > pbes2_encrypt_iter(std::span< const uint8_t > key_bits, std::string_view passphrase, size_t pbkdf_iter, std::string_view cipher, std::string_view digest, RandomNumberGenerator &rng)
Definition pbes2.cpp:414

References BOTAN_UNUSED, Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::OctetString, Botan::pbes2_encrypt_iter(), Botan::Private_Key::private_key_info(), and Botan::DER_Encoder::start_sequence().

Referenced by botan_privkey_view_encrypted_der(), 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,
std::string_view pass,
std::chrono::milliseconds pbkdf_msec,
size_t * pbkdf_iterations,
std::string_view cipher = "",
std::string_view pbkdf_hash = "" )

Encrypt a key using PKCS #8 encryption and a variable iteration count

Parameters
keythe key to encode
Random Number Generatorsthe 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 251 of file pkcs8.cpp.

257 {
258#if defined(BOTAN_HAS_PKCS5_PBES2)
259 const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
261 pass,
262 pbkdf_msec,
263 pbkdf_iterations,
264 cipher.empty() ? "AES-256/CBC" : cipher,
265 pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
266 rng);
267
268 std::vector<uint8_t> output;
269 DER_Encoder(output)
271 .encode(pbe_info.first)
272 .encode(pbe_info.second, ASN1_Type::OctetString)
273 .end_cons();
274
275 return output;
276#else
277 BOTAN_UNUSED(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash);
278 throw Encoding_Error("BER_encode_encrypted_pbkdf_msec cannot encrypt because PBES2 disabled in build");
279#endif
280}
DER_Encoder & start_sequence()
Definition der_enc.h:86
DER_Encoder & end_cons()
Definition der_enc.cpp:208
DER_Encoder & encode(bool b)
Definition der_enc.cpp:313

References BOTAN_UNUSED, Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::OctetString, Botan::pbes2_encrypt_msec(), Botan::Private_Key::private_key_info(), and Botan::DER_Encoder::start_sequence().

Referenced by botan_privkey_view_encrypted_der_timed(), and PEM_encode_encrypted_pbkdf_msec().

◆ copy_key()

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

Copy an existing encoded key object.

Parameters
keythe key to copy
Returns
new copy of the key

Definition at line 236 of file pkcs8.h.

236 {
238 return PKCS8::load_key(source);
239}
std::unique_ptr< Private_Key > load_key(DataSource &source, const std::function< std::string()> &get_pass)
Definition pkcs8.cpp:320

References copy_key(), and load_key().

Referenced by 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 351 of file pkcs8.cpp.

351 {
352 const auto fail_fn = []() -> std::string {
353 throw PKCS8_Exception("Internal error: Attempt to read password for unencrypted key");
354 };
355
356 return load_key(source, fail_fn, false);
357}

References load_key().

◆ load_key() [2/6]

std::unique_ptr< Private_Key > Botan::PKCS8::load_key ( DataSource & source,
const 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 320 of file pkcs8.cpp.

320 {
321 return load_key(source, get_pass, true);
322}

References load_key().

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

◆ load_key() [3/6]

std::unique_ptr< Private_Key > Botan::PKCS8::load_key ( DataSource & source,
std::string_view 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 343 of file pkcs8.cpp.

343 {
344 return load_key(
345 source, [pass]() { return std::string(pass); }, true);
346}

References load_key().

◆ load_key() [4/6]

std::unique_ptr< Private_Key > Botan::PKCS8::load_key ( std::span< const uint8_t > source)

Load an unencrypted key from memory.

Parameters
sourcethe byte buffer containing the encoded key
Returns
loaded private key object

Definition at line 335 of file pkcs8.cpp.

335 {
336 Botan::DataSource_Memory ds(source);
337 return load_key(ds);
338}

References load_key().

◆ load_key() [5/6]

std::unique_ptr< Private_Key > Botan::PKCS8::load_key ( std::span< const uint8_t > source,
const std::function< std::string()> & get_passphrase )

Load an encrypted key from memory.

Parameters
sourcethe byte buffer containing the encoded key
get_passphrasea function that returns passphrases
Returns
loaded private key object

Definition at line 324 of file pkcs8.cpp.

325 {
326 Botan::DataSource_Memory ds(source);
327 return load_key(ds, get_passphrase);
328}

References load_key().

◆ load_key() [6/6]

std::unique_ptr< Private_Key > Botan::PKCS8::load_key ( std::span< const uint8_t > source,
std::string_view pass )

Load an encrypted key from memory.

Parameters
sourcethe byte buffer containing the encoded key
passthe passphrase to decrypt the key
Returns
loaded private key object

Definition at line 330 of file pkcs8.cpp.

330 {
331 Botan::DataSource_Memory ds(source);
332 return load_key(ds, pass);
333}

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

122 {
123 return PEM_Code::encode(key.private_key_info(), "PRIVATE KEY");
124}
std::string encode(const uint8_t der[], size_t length, std::string_view label, size_t width)
Definition pem.cpp:41

References Botan::PEM_Code::encode(), and Botan::Private_Key::private_key_info().

Referenced by botan_privkey_view_pem(), and PEM_encode().

◆ PEM_encode() [2/2]

std::string Botan::PKCS8::PEM_encode ( const Private_Key & key,
RandomNumberGenerator & rng,
std::string_view pass,
std::chrono::milliseconds msec = std::chrono::milliseconds(300),
std::string_view pbe_algo = "" )

Get a string containing a PEM encoded private key, encrypting it with a password.

Parameters
keythe key to encode
Random Number Generatorsthe 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 193 of file pkcs8.cpp.

197 {
198 if(pass.empty()) {
199 return PEM_encode(key);
200 }
201
202 return PEM_Code::encode(PKCS8::BER_encode(key, rng, pass, msec, pbe_algo), "ENCRYPTED PRIVATE KEY");
203}
std::string PEM_encode(const Private_Key &key)
Definition pkcs8.cpp:122

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,
std::string_view pass,
size_t pbkdf_iter,
std::string_view cipher = "",
std::string_view pbkdf_hash = "" )

Get a string containing a PEM encoded private key, encrypting it with a password.

Parameters
keythe key to encode
Random Number Generatorsthe 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 238 of file pkcs8.cpp.

243 {
244 return PEM_Code::encode(PKCS8::BER_encode_encrypted_pbkdf_iter(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash),
245 "ENCRYPTED PRIVATE KEY");
246}
std::vector< uint8_t > BER_encode_encrypted_pbkdf_iter(const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, size_t pbkdf_iterations, std::string_view cipher, std::string_view pbkdf_hash)
Definition pkcs8.cpp:208

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

Referenced by botan_privkey_view_encrypted_pem().

◆ PEM_encode_encrypted_pbkdf_msec()

std::string Botan::PKCS8::PEM_encode_encrypted_pbkdf_msec ( const Private_Key & key,
RandomNumberGenerator & rng,
std::string_view pass,
std::chrono::milliseconds pbkdf_msec,
size_t * pbkdf_iterations,
std::string_view cipher = "",
std::string_view pbkdf_hash = "" )

Get a string containing a PEM encoded private key, encrypting it with a password.

Parameters
keythe key to encode
Random Number Generatorsthe 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 285 of file pkcs8.cpp.

291 {
292 return PEM_Code::encode(
293 PKCS8::BER_encode_encrypted_pbkdf_msec(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash),
294 "ENCRYPTED PRIVATE KEY");
295}
std::vector< uint8_t > BER_encode_encrypted_pbkdf_msec(const Private_Key &key, RandomNumberGenerator &rng, std::string_view pass, std::chrono::milliseconds pbkdf_msec, size_t *pbkdf_iterations, std::string_view cipher, std::string_view pbkdf_hash)
Definition pkcs8.cpp:251

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

Referenced by botan_privkey_view_encrypted_pem_timed().