Botan 3.8.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 164 of file pkcs8.cpp.

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

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_privkey_view_der(), 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 204 of file pkcs8.cpp.

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

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

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

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

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

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

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

317 {
318 return load_key(source, get_pass, true);
319}

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

340 {
341 return load_key(
342 source, [pass]() { return std::string(pass); }, true);
343}

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

332 {
333 Botan::DataSource_Memory ds(source);
334 return load_key(ds);
335}

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

322 {
323 Botan::DataSource_Memory ds(source);
324 return load_key(ds, get_passphrase);
325}

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

327 {
328 Botan::DataSource_Memory ds(source);
329 return load_key(ds, pass);
330}

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

119 {
120 return PEM_Code::encode(key.private_key_info(), "PRIVATE KEY");
121}
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 189 of file pkcs8.cpp.

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

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

239 {
240 return PEM_Code::encode(PKCS8::BER_encode_encrypted_pbkdf_iter(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash),
241 "ENCRYPTED PRIVATE KEY");
242}
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:204

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

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

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

Referenced by botan_privkey_view_encrypted_pem_timed().