Botan 3.2.0
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, 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:60

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

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

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

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

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 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,
257 pbkdf_msec,
258 pbkdf_iterations,
259 cipher.empty() ? "AES-256/CBC" : cipher,
260 pbkdf_hash.empty() ? "SHA-256" : pbkdf_hash,
261 rng);
262
263 std::vector<uint8_t> output;
264 DER_Encoder(output)
266 .encode(pbe_info.first)
267 .encode(pbe_info.second, ASN1_Type::OctetString)
268 .end_cons();
269
270 return output;
271#else
272 BOTAN_UNUSED(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash);
273 throw Encoding_Error("BER_encode_encrypted_pbkdf_msec cannot encrypt because PBES2 disabled in build");
274#endif
275}
DER_Encoder & start_sequence()
Definition der_enc.h:65
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}

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

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

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

316 {
317 return load_key(source, get_pass, true);
318}
std::unique_ptr< Private_Key > load_key(DataSource &source, const std::function< std::string()> &get_pass)
Definition pkcs8.cpp: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 339 of file pkcs8.cpp.

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

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

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

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

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

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

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

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

118 {
119 return PEM_Code::encode(key.private_key_info(), "PRIVATE KEY");
120}

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

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

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

238 {
239 return PEM_Code::encode(PKCS8::BER_encode_encrypted_pbkdf_iter(key, rng, pass, pbkdf_iterations, cipher, pbkdf_hash),
240 "ENCRYPTED PRIVATE KEY");
241}

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

286 {
287 return PEM_Code::encode(
288 PKCS8::BER_encode_encrypted_pbkdf_msec(key, rng, pass, pbkdf_msec, pbkdf_iterations, cipher, pbkdf_hash),
289 "ENCRYPTED PRIVATE KEY");
290}

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

Referenced by botan_privkey_view_encrypted_pem_timed().