Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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