Botan  2.1.0
Crypto and TLS for C++11
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
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
secure_vector< uint8_t > BER_encode(const Private_Key &key)
Definition: pkcs8.cpp:130
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
std::string PEM_encode(const Private_Key &key)
Definition: pkcs8.cpp:139
Private_Key * load_key(DataSource &source, RandomNumberGenerator &rng, std::function< std::string()> get_pass)
Definition: pkcs8.cpp:313
Private_Key * copy_key(const Private_Key &key, RandomNumberGenerator &rng)
Definition: pkcs8.cpp:378
Definition: alg_id.cpp:13
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
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
PKCS8_Exception(const std::string &error)
Definition: pkcs8.h:22