Botan 3.0.0-alpha0
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::function< std::string()> &get_pass)
 
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_passphrase)
 
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)
inline

BER encode a private key

Parameters
keythe private key to encode
Returns
BER encoded key

Definition at line 43 of file pkcs8.h.

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

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

194 {
195#if defined(BOTAN_HAS_PKCS5_PBES2)
196 const auto pbe_params = choose_pbe_params(pbe_algo, key.algo_name());
197
198 const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
199 pbes2_encrypt_msec(PKCS8::BER_encode(key), pass, msec, nullptr,
200 pbe_params.first, pbe_params.second, rng);
201
202 std::vector<uint8_t> output;
203 DER_Encoder der(output);
204 der.start_sequence()
205 .encode(pbe_info.first)
206 .encode(pbe_info.second, ASN1_Type::OctetString)
207 .end_cons();
208
209 return output;
210#else
211 BOTAN_UNUSED(key, rng, pass, msec, pbe_algo);
212 throw Encoding_Error("PKCS8::BER_encode cannot encrypt because PBES2 was disabled in build");
213#endif
214 }
#define BOTAN_UNUSED(...)
Definition: assert.h:141
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:189
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:271

References Botan::Public_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_export(), 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,
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 235 of file pkcs8.cpp.

241 {
242#if defined(BOTAN_HAS_PKCS5_PBES2)
243 const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
245 pass, pbkdf_iterations,
246 cipher.empty() ? "AES-256/CBC" : cipher,
247 pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
248 rng);
249
250 std::vector<uint8_t> output;
251 DER_Encoder der(output);
252 der.start_sequence()
253 .encode(pbe_info.first)
254 .encode(pbe_info.second, ASN1_Type::OctetString)
255 .end_cons();
256
257 return output;
258
259#else
260 BOTAN_UNUSED(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash);
261 throw Encoding_Error("PKCS8::BER_encode_encrypted_pbkdf_iter cannot encrypt because PBES2 disabled in build");
262#endif
263 }
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:290

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

290 {
291#if defined(BOTAN_HAS_PKCS5_PBES2)
292 const std::pair<AlgorithmIdentifier, std::vector<uint8_t>> pbe_info =
294 pbkdf_msec, pbkdf_iterations,
295 cipher.empty() ? "AES-256/CBC" : cipher,
296 pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
297 rng);
298
299 std::vector<uint8_t> output;
300 DER_Encoder(output)
302 .encode(pbe_info.first)
303 .encode(pbe_info.second, ASN1_Type::OctetString)
304 .end_cons();
305
306 return output;
307#else
308 BOTAN_UNUSED(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash);
309 throw Encoding_Error("BER_encode_encrypted_pbkdf_msec cannot encrypt because PBES2 disabled in build");
310#endif
311 }
DER_Encoder & start_sequence()
Definition: der_enc.h:66
DER_Encoder & end_cons()
Definition: der_enc.cpp:194
DER_Encoder & encode(bool b)
Definition: der_enc.cpp:288

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_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)
inline

Copy an existing encoded key object.

Parameters
keythe key to copy
Returns
new copy of the key

Definition at line 214 of file pkcs8.h.

215 {
217 return PKCS8::load_key(source);
218 }
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng)
Definition: pkcs8.h:259

References load_key().

Referenced by copy_key().

◆ copy_key() [2/2]

Private_Key * Botan::PKCS8::copy_key ( const Private_Key key,
RandomNumberGenerator rng 
)
inline

Copy an existing encoded key object.

Parameters
keythe key to copy
rngignored for compatibility
Returns
new copy of the key

Definition at line 324 of file pkcs8.h.

326 {
327 BOTAN_UNUSED(rng);
328 return PKCS8::copy_key(key).release();
329 }
Private_Key * copy_key(const Private_Key &key, RandomNumberGenerator &rng)
Definition: pkcs8.h:324

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

376 {
377 auto fail_fn = []() -> std::string {
378 throw PKCS8_Exception("Internal error: Attempt to read password for unencrypted key");
379 };
380
381 return load_key(source, fail_fn, false);
382 }
std::unique_ptr< Private_Key > load_key(DataSource &source)
Definition: pkcs8.cpp:375

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

357 {
358 return load_key(source, get_pass, true);
359 }

References load_key().

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

◆ load_key() [3/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 364 of file pkcs8.cpp.

366 {
367 // We need to use bind rather than a lambda capturing `pass` here in order to avoid a Clang 8 bug.
368 // See https://github.com/randombit/botan/issues/2255.
369 return load_key(source, std::bind([](const std::string& p) { return p; }, pass), true);
370 }

References load_key().

◆ load_key() [4/6]

Private_Key * Botan::PKCS8::load_key ( DataSource source,
RandomNumberGenerator rng 
)
inline

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 259 of file pkcs8.h.

261 {
262 BOTAN_UNUSED(rng);
263 return PKCS8::load_key(source).release();
264 }

References BOTAN_UNUSED, and load_key().

◆ load_key() [5/6]

Private_Key * Botan::PKCS8::load_key ( DataSource source,
RandomNumberGenerator rng,
const std::string &  pass 
)
inline

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 245 of file pkcs8.h.

248 {
249 BOTAN_UNUSED(rng);
250 return PKCS8::load_key(source, pass).release();
251 }

References BOTAN_UNUSED, and load_key().

◆ load_key() [6/6]

Private_Key * Botan::PKCS8::load_key ( DataSource source,
RandomNumberGenerator rng,
std::function< std::string()>  get_passphrase 
)
inline

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 230 of file pkcs8.h.

233 {
234 BOTAN_UNUSED(rng);
235 return PKCS8::load_key(source, get_passphrase).release();
236 }

References BOTAN_UNUSED, 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 137 of file pkcs8.cpp.

138 {
139 return PEM_Code::encode(key.private_key_info(), "PRIVATE KEY");
140 }
std::string encode(const uint8_t der[], size_t length, const std::string &label, size_t width)
Definition: pem.cpp:41

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

Referenced by botan_privkey_export(), 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 219 of file pkcs8.cpp.

224 {
225 if(pass.empty())
226 return PEM_encode(key);
227
228 return PEM_Code::encode(PKCS8::BER_encode(key, rng, pass, msec, pbe_algo),
229 "ENCRYPTED PRIVATE KEY");
230 }
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:219

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

274 {
275 return PEM_Code::encode(
276 PKCS8::BER_encode_encrypted_pbkdf_iter(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash),
277 "ENCRYPTED PRIVATE KEY");
278 }
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:235

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

323 {
324 return PEM_Code::encode(
325 PKCS8::BER_encode_encrypted_pbkdf_msec(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash),
326 "ENCRYPTED PRIVATE KEY");
327 }
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:283

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

Referenced by botan_privkey_export_encrypted_pbkdf_msec().