/src/botan/build/include/public/botan/pkcs8.h

Source (jump to first uncovered line)
/*
* PKCS #8
* (C) 1999-2007,2023 Jack Lloyd
*
* Botan is released under the Simplified BSD License (see license.txt)
*/

#ifndef BOTAN_PKCS8_H_
#define BOTAN_PKCS8_H_

#include <botan/data_src.h>
#include <botan/exceptn.h>
#include <botan/pk_keys.h>
#include <botan/secmem.h>
#include <chrono>
#include <functional>
#include <memory>
#include <span>
#include <string_view>

namespace Botan {

class RandomNumberGenerator;

/**
* PKCS #8 General Exception
*/
class BOTAN_PUBLIC_API(2, 0) PKCS8_Exception final : public Decoding_Error {
   public:
      explicit PKCS8_Exception(std::string_view error) : Decoding_Error("PKCS #8", error) {}
};

/**
* This namespace contains functions for handling PKCS #8 private keys
*/
namespace PKCS8 {

/**
* BER encode a private key
* @param key the private key to encode
* @return BER encoded key
*/
inline secure_vector<uint8_t> BER_encode(const Private_Key& key) {
   return key.private_key_info();
}

/**
* Get a string containing a PEM encoded private key.
* @param key the key to encode
* @return encoded key
*/
BOTAN_PUBLIC_API(2, 0) std::string PEM_encode(const Private_Key& key);

/**
* Encrypt a key using PKCS #8 encryption
* @param key the key to encode
* @param rng the rng to use
* @param pass the password to use for encryption
* @param msec number of milliseconds to run the password derivation
* @param pbe_algo the name of the desired password-based encryption
*        algorithm; if empty ("") a reasonable (portable/secure)
*        default will be chosen.
* @return encrypted key in binary BER form
*/
BOTAN_PUBLIC_API(2, 0)
std::vector<uint8_t> 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 = "");

/**
* Get a string containing a PEM encoded private key, encrypting it with a
* password.
* @param key the key to encode
* @param rng the rng to use
* @param pass the password to use for encryption
* @param msec number of milliseconds to run the password derivation
* @param pbe_algo the name of the desired password-based encryption
*        algorithm; if empty ("") a reasonable (portable/secure)
*        default will be chosen.
* @return encrypted key in PEM form
*/
BOTAN_PUBLIC_API(2, 0)
std::string 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 = "");

/**
* Encrypt a key using PKCS #8 encryption and a fixed iteration count
* @param key the key to encode
* @param rng the rng to use
* @param pass the password to use for encryption
* @param pbkdf_iter number of interations to run PBKDF2
* @param cipher if 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.
* @param pbkdf_hash if non-empty specifies the PBKDF hash function to use.
*   For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.
* @return encrypted key in binary BER form
*/
BOTAN_PUBLIC_API(2, 1)
std::vector<uint8_t> 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 = "");

/**
* Get a string containing a PEM encoded private key, encrypting it with a
* password.
* @param key the key to encode
* @param rng the rng to use
* @param pass the password to use for encryption
* @param pbkdf_iter number of iterations to run PBKDF
* @param cipher if 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.
* @param pbkdf_hash if non-empty specifies the PBKDF hash function to use.
*   For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.
* @return encrypted key in PEM form
*/
BOTAN_PUBLIC_API(2, 1)
std::string 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 = "");

/**
* Encrypt a key using PKCS #8 encryption and a variable iteration count
* @param key the key to encode
* @param rng the rng to use
* @param pass the password to use for encryption
* @param pbkdf_msec how long to run PBKDF2
* @param pbkdf_iterations if non-null, set to the number of iterations used
* @param cipher if 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.
* @param pbkdf_hash if non-empty specifies the PBKDF hash function to use.
*   For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.
* @return encrypted key in binary BER form
*/
BOTAN_PUBLIC_API(2, 1)
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 = "");

/**
* Get a string containing a PEM encoded private key, encrypting it with a
* password.
* @param key the key to encode
* @param rng the rng to use
* @param pass the password to use for encryption
* @param pbkdf_msec how long in milliseconds to run PBKDF2
* @param pbkdf_iterations (output argument) number of iterations of PBKDF
*  that ended up being used
* @param cipher if 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.
* @param pbkdf_hash if non-empty specifies the PBKDF hash function to use.
*   For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.
* @return encrypted key in PEM form
*/
BOTAN_PUBLIC_API(2, 1)
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 = "");

/**
* Load an encrypted key from a data source.
* @param source the data source providing the encoded key
* @param get_passphrase a function that returns passphrases
* @return loaded private key object
*/
BOTAN_PUBLIC_API(2, 3)
std::unique_ptr<Private_Key> load_key(DataSource& source, const std::function<std::string()>& get_passphrase);

/** Load an encrypted key from a data source.
* @param source the data source providing the encoded key
* @param pass the passphrase to decrypt the key
* @return loaded private key object
*/
BOTAN_PUBLIC_API(2, 3)
std::unique_ptr<Private_Key> load_key(DataSource& source, std::string_view pass);

/** Load an unencrypted key from a data source.
* @param source the data source providing the encoded key
* @return loaded private key object
*/
BOTAN_PUBLIC_API(2, 3)
std::unique_ptr<Private_Key> load_key(DataSource& source);

/**
* Load an encrypted key from memory.
* @param source the byte buffer containing the encoded key
* @param get_passphrase a function that returns passphrases
* @return loaded private key object
*/
BOTAN_PUBLIC_API(3, 0)
std::unique_ptr<Private_Key> load_key(std::span<const uint8_t> source,
                                      const std::function<std::string()>& get_passphrase);

/** Load an encrypted key from memory.
* @param source the byte buffer containing the encoded key
* @param pass the passphrase to decrypt the key
* @return loaded private key object
*/
BOTAN_PUBLIC_API(3, 0)
std::unique_ptr<Private_Key> load_key(std::span<const uint8_t> source, std::string_view pass);

/** Load an unencrypted key from memory.
* @param source the byte buffer containing the encoded key
* @return loaded private key object
*/
BOTAN_PUBLIC_API(3, 0)
std::unique_ptr<Private_Key> load_key(std::span<const uint8_t> source);

/**
* Copy an existing encoded key object.
* @param key the key to copy
* @return new copy of the key
*/
inline std::unique_ptr<Private_Key> copy_key(const Private_Key& key) {
   DataSource_Memory source(key.private_key_info());
   return PKCS8::load_key(source);
}

}  // namespace PKCS8

}  // namespace Botan

#endif

Coverage Report

Created: 2025-04-11 06:34

Line	Count	Source (jump to first uncovered line)
1		/*
2		* PKCS #8
3		* (C) 1999-2007,2023 Jack Lloyd
4		*
5		* Botan is released under the Simplified BSD License (see license.txt)
6		*/
7
8		#ifndef BOTAN_PKCS8_H_
9		#define BOTAN_PKCS8_H_
10
11		#include <botan/data_src.h>
12		#include <botan/exceptn.h>
13		#include <botan/pk_keys.h>
14		#include <botan/secmem.h>
15		#include <chrono>
16		#include <functional>
17		#include <memory>
18		#include <span>
19		#include <string_view>
20
21		namespace Botan {
22
23		class RandomNumberGenerator;
24
25		/**
26		* PKCS #8 General Exception
27		*/
28		class BOTAN_PUBLIC_API(2, 0) PKCS8_Exception final : public Decoding_Error {
29		public:
30	434	explicit PKCS8_Exception(std::string_view error) : Decoding_Error("PKCS #8", error) {}
31		};
32
33		/**
34		* This namespace contains functions for handling PKCS #8 private keys
35		*/
36		namespace PKCS8 {
37
38		/**
39		* BER encode a private key
40		* @param key the private key to encode
41		* @return BER encoded key
42		*/
43	0	inline secure_vector<uint8_t> BER_encode(const Private_Key& key) {
44	0	return key.private_key_info();
45	0	}
46
47		/**
48		* Get a string containing a PEM encoded private key.
49		* @param key the key to encode
50		* @return encoded key
51		*/
52		BOTAN_PUBLIC_API(2, 0) std::string PEM_encode(const Private_Key& key);
53
54		/**
55		* Encrypt a key using PKCS #8 encryption
56		* @param key the key to encode
57		* @param rng the rng to use
58		* @param pass the password to use for encryption
59		* @param msec number of milliseconds to run the password derivation
60		* @param pbe_algo the name of the desired password-based encryption
61		* algorithm; if empty ("") a reasonable (portable/secure)
62		* default will be chosen.
63		* @return encrypted key in binary BER form
64		*/
65		BOTAN_PUBLIC_API(2, 0)
66		std::vector<uint8_t> BER_encode(const Private_Key& key,
67		RandomNumberGenerator& rng,
68		std::string_view pass,
69		std::chrono::milliseconds msec = std::chrono::milliseconds(300),
70		std::string_view pbe_algo = "");
71
72		/**
73		* Get a string containing a PEM encoded private key, encrypting it with a
74		* password.
75		* @param key the key to encode
76		* @param rng the rng to use
77		* @param pass the password to use for encryption
78		* @param msec number of milliseconds to run the password derivation
79		* @param pbe_algo the name of the desired password-based encryption
80		* algorithm; if empty ("") a reasonable (portable/secure)
81		* default will be chosen.
82		* @return encrypted key in PEM form
83		*/
84		BOTAN_PUBLIC_API(2, 0)
85		std::string PEM_encode(const Private_Key& key,
86		RandomNumberGenerator& rng,
87		std::string_view pass,
88		std::chrono::milliseconds msec = std::chrono::milliseconds(300),
89		std::string_view pbe_algo = "");
90
91		/**
92		* Encrypt a key using PKCS #8 encryption and a fixed iteration count
93		* @param key the key to encode
94		* @param rng the rng to use
95		* @param pass the password to use for encryption
96		* @param pbkdf_iter number of interations to run PBKDF2
97		* @param cipher if non-empty specifies the cipher to use. CBC and GCM modes
98		* are supported, for example "AES-128/CBC", "AES-256/GCM", "Serpent/CBC".
99		* If empty a suitable default is chosen.
100		* @param pbkdf_hash if non-empty specifies the PBKDF hash function to use.
101		* For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.
102		* @return encrypted key in binary BER form
103		*/
104		BOTAN_PUBLIC_API(2, 1)
105		std::vector<uint8_t> BER_encode_encrypted_pbkdf_iter(const Private_Key& key,
106		RandomNumberGenerator& rng,
107		std::string_view pass,
108		size_t pbkdf_iter,
109		std::string_view cipher = "",
110		std::string_view pbkdf_hash = "");
111
112		/**
113		* Get a string containing a PEM encoded private key, encrypting it with a
114		* password.
115		* @param key the key to encode
116		* @param rng the rng to use
117		* @param pass the password to use for encryption
118		* @param pbkdf_iter number of iterations to run PBKDF
119		* @param cipher if non-empty specifies the cipher to use. CBC and GCM modes
120		* are supported, for example "AES-128/CBC", "AES-256/GCM", "Serpent/CBC".
121		* If empty a suitable default is chosen.
122		* @param pbkdf_hash if non-empty specifies the PBKDF hash function to use.
123		* For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.
124		* @return encrypted key in PEM form
125		*/
126		BOTAN_PUBLIC_API(2, 1)
127		std::string PEM_encode_encrypted_pbkdf_iter(const Private_Key& key,
128		RandomNumberGenerator& rng,
129		std::string_view pass,
130		size_t pbkdf_iter,
131		std::string_view cipher = "",
132		std::string_view pbkdf_hash = "");
133
134		/**
135		* Encrypt a key using PKCS #8 encryption and a variable iteration count
136		* @param key the key to encode
137		* @param rng the rng to use
138		* @param pass the password to use for encryption
139		* @param pbkdf_msec how long to run PBKDF2
140		* @param pbkdf_iterations if non-null, set to the number of iterations used
141		* @param cipher if non-empty specifies the cipher to use. CBC and GCM modes
142		* are supported, for example "AES-128/CBC", "AES-256/GCM", "Serpent/CBC".
143		* If empty a suitable default is chosen.
144		* @param pbkdf_hash if non-empty specifies the PBKDF hash function to use.
145		* For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.
146		* @return encrypted key in binary BER form
147		*/
148		BOTAN_PUBLIC_API(2, 1)
149		std::vector<uint8_t> BER_encode_encrypted_pbkdf_msec(const Private_Key& key,
150		RandomNumberGenerator& rng,
151		std::string_view pass,
152		std::chrono::milliseconds pbkdf_msec,
153		size_t* pbkdf_iterations,
154		std::string_view cipher = "",
155		std::string_view pbkdf_hash = "");
156
157		/**
158		* Get a string containing a PEM encoded private key, encrypting it with a
159		* password.
160		* @param key the key to encode
161		* @param rng the rng to use
162		* @param pass the password to use for encryption
163		* @param pbkdf_msec how long in milliseconds to run PBKDF2
164		* @param pbkdf_iterations (output argument) number of iterations of PBKDF
165		* that ended up being used
166		* @param cipher if non-empty specifies the cipher to use. CBC and GCM modes
167		* are supported, for example "AES-128/CBC", "AES-256/GCM", "Serpent/CBC".
168		* If empty a suitable default is chosen.
169		* @param pbkdf_hash if non-empty specifies the PBKDF hash function to use.
170		* For example "SHA-256" or "SHA-384". If empty a suitable default is chosen.
171		* @return encrypted key in PEM form
172		*/
173		BOTAN_PUBLIC_API(2, 1)
174		std::string PEM_encode_encrypted_pbkdf_msec(const Private_Key& key,
175		RandomNumberGenerator& rng,
176		std::string_view pass,
177		std::chrono::milliseconds pbkdf_msec,
178		size_t* pbkdf_iterations,
179		std::string_view cipher = "",
180		std::string_view pbkdf_hash = "");
181
182		/**
183		* Load an encrypted key from a data source.
184		* @param source the data source providing the encoded key
185		* @param get_passphrase a function that returns passphrases
186		* @return loaded private key object
187		*/
188		BOTAN_PUBLIC_API(2, 3)
189		std::unique_ptr<Private_Key> load_key(DataSource& source, const std::function<std::string()>& get_passphrase);
190
191		/** Load an encrypted key from a data source.
192		* @param source the data source providing the encoded key
193		* @param pass the passphrase to decrypt the key
194		* @return loaded private key object
195		*/
196		BOTAN_PUBLIC_API(2, 3)
197		std::unique_ptr<Private_Key> load_key(DataSource& source, std::string_view pass);
198
199		/** Load an unencrypted key from a data source.
200		* @param source the data source providing the encoded key
201		* @return loaded private key object
202		*/
203		BOTAN_PUBLIC_API(2, 3)
204		std::unique_ptr<Private_Key> load_key(DataSource& source);
205
206		/**
207		* Load an encrypted key from memory.
208		* @param source the byte buffer containing the encoded key
209		* @param get_passphrase a function that returns passphrases
210		* @return loaded private key object
211		*/
212		BOTAN_PUBLIC_API(3, 0)
213		std::unique_ptr<Private_Key> load_key(std::span<const uint8_t> source,
214		const std::function<std::string()>& get_passphrase);
215
216		/** Load an encrypted key from memory.
217		* @param source the byte buffer containing the encoded key
218		* @param pass the passphrase to decrypt the key
219		* @return loaded private key object
220		*/
221		BOTAN_PUBLIC_API(3, 0)
222		std::unique_ptr<Private_Key> load_key(std::span<const uint8_t> source, std::string_view pass);
223
224		/** Load an unencrypted key from memory.
225		* @param source the byte buffer containing the encoded key
226		* @return loaded private key object
227		*/
228		BOTAN_PUBLIC_API(3, 0)
229		std::unique_ptr<Private_Key> load_key(std::span<const uint8_t> source);
230
231		/**
232		* Copy an existing encoded key object.
233		* @param key the key to copy
234		* @return new copy of the key
235		*/
236	0	inline std::unique_ptr<Private_Key> copy_key(const Private_Key& key) {
237	0	DataSource_Memory source(key.private_key_info());
238	0	return PKCS8::load_key(source);
239	0	}
240
241		} // namespace PKCS8
242
243		} // namespace Botan
244
245		#endif