Botan 3.9.0
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_Keycopy_key (const Private_Key &key)
std::unique_ptr< Private_Keyload_key (DataSource &source)
std::unique_ptr< Private_Keyload_key (DataSource &source, const std::function< std::string()> &get_pass)
std::unique_ptr< Private_Keyload_key (DataSource &source, std::string_view pass)
std::unique_ptr< Private_Keyload_key (std::span< const uint8_t > source)
std::unique_ptr< Private_Keyload_key (std::span< const uint8_t > source, const std::function< std::string()> &get_passphrase)
std::unique_ptr< Private_Keyload_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:68

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

165 {
166#if defined(BOTAN_HAS_PKCS5_PBES2)
167 const auto pbe_params = choose_pbe_params(pbe_algo, key.algo_name());
168
169 const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
170 pbes2_encrypt_msec(PKCS8::BER_encode(key), pass, msec, nullptr, pbe_params.first, pbe_params.second, rng);
171
172 std::vector<uint8_t> output;
173 DER_Encoder der(output);
174 der.start_sequence().encode(pbe_info.first).encode(pbe_info.second, ASN1_Type::OctetString).end_cons();
175
176 return output;
177#else
178 BOTAN_UNUSED(key, rng, pass, msec, pbe_algo);
179 throw Encoding_Error("PKCS8::BER_encode cannot encrypt because PBES2 was disabled in build");
180#endif
181}
#define BOTAN_UNUSED
Definition assert.h:144
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:161
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:256

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

206 {
207#if defined(BOTAN_HAS_PKCS5_PBES2)
208 const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
210 pass,
211 pbkdf_iterations,
212 cipher.empty() ? "AES-256/CBC" : cipher,
213 pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
214 rng);
215
216 std::vector<uint8_t> output;
217 DER_Encoder der(output);
218 der.start_sequence().encode(pbe_info.first).encode(pbe_info.second, ASN1_Type::OctetString).end_cons();
219
220 return output;
221
222#else
223 BOTAN_UNUSED(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash);
224 throw Encoding_Error("PKCS8::BER_encode_encrypted_pbkdf_iter cannot encrypt because PBES2 disabled in build");
225#endif
226}
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:274

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

250 {
251#if defined(BOTAN_HAS_PKCS5_PBES2)
252 const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
254 pass,
255 pbkdf_msec,
256 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(output)
264 .encode(pbe_info.first)
265 .encode(pbe_info.second, ASN1_Type::OctetString)
266 .end_cons();
267
268 return output;
269#else
270 BOTAN_UNUSED(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash);
271 throw Encoding_Error("BER_encode_encrypted_pbkdf_msec cannot encrypt because PBES2 disabled in build");
272#endif
273}
DER_Encoder & start_sequence()
Definition der_enc.h:65
DER_Encoder & end_cons()
Definition der_enc.cpp:173
DER_Encoder & encode(bool b)
Definition der_enc.cpp:252

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:314

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

345 {
346 auto fail_fn = []() -> std::string {
347 throw PKCS8_Exception("Internal error: Attempt to read password for unencrypted key");
348 };
349
350 return load_key(source, fail_fn, false);
351}

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

314 {
315 return load_key(source, get_pass, true);
316}

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

337 {
338 return load_key(
339 source, [pass]() { return std::string(pass); }, true);
340}

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

329 {
330 Botan::DataSource_Memory ds(source);
331 return load_key(ds);
332}

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

319 {
320 Botan::DataSource_Memory ds(source);
321 return load_key(ds, get_passphrase);
322}

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

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

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

116 {
117 return PEM_Code::encode(key.private_key_info(), "PRIVATE KEY");
118}
std::string encode(const uint8_t der[], size_t length, std::string_view label, size_t width)
Definition pem.cpp:39

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

190 {
191 if(pass.empty()) {
192 return PEM_encode(key);
193 }
194
195 return PEM_Code::encode(PKCS8::BER_encode(key, rng, pass, msec, pbe_algo), "ENCRYPTED PRIVATE KEY");
196}
std::string PEM_encode(const Private_Key &key)
Definition pkcs8.cpp:116

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

236 {
237 return PEM_Code::encode(PKCS8::BER_encode_encrypted_pbkdf_iter(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash),
238 "ENCRYPTED PRIVATE KEY");
239}
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:201

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

284 {
285 return PEM_Code::encode(
286 PKCS8::BER_encode_encrypted_pbkdf_msec(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash),
287 "ENCRYPTED PRIVATE KEY");
288}
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:244

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

Referenced by botan_privkey_view_encrypted_pem_timed().