Botan 2.13.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

pbkdf.h
Go to the documentation of this file.
1 /*
2 * PBKDF
3 * (C) 1999-2007,2012,2015 Jack Lloyd
4 *
5 * Botan is released under the Simplified BSD License (see license.txt)
6 */
7
8 #ifndef BOTAN_PBKDF_H_
9 #define BOTAN_PBKDF_H_
10
11 #include <botan/symkey.h>
12 #include <chrono>
13
14 namespace Botan {
15
16 /**
17 * Base class for PBKDF (password based key derivation function)
18 * implementations. Converts a password into a key using a salt
19 * and iterated hashing to make brute force attacks harder.
20 *
21 * Starting in 2.8 this functionality is also offered by PasswordHash.
22 * The PBKDF interface may be removed in a future release.
23 */
24 class BOTAN_PUBLIC_API(2,0) PBKDF
25 {
26 public:
27 /**
28 * Create an instance based on a name
29 * If provider is empty then best available is chosen.
30 * @param algo_spec algorithm name
31 * @param provider provider implementation to choose
32 * @return a null pointer if the algo/provider combination cannot be found
33 */
34 static std::unique_ptr<PBKDF> create(const std::string& algo_spec,
35 const std::string& provider = "");
36
37 /**
38 * Create an instance based on a name, or throw if the
39 * algo/provider combination cannot be found. If provider is
40 * empty then best available is chosen.
41 */
42 static std::unique_ptr<PBKDF>
43 create_or_throw(const std::string& algo_spec,
44 const std::string& provider = "");
45
46 /**
47 * @return list of available providers for this algorithm, empty if not available
48 */
49 static std::vector<std::string> providers(const std::string& algo_spec);
50
51 /**
52 * @return new instance of this same algorithm
53 */
54 virtual PBKDF* clone() const = 0;
55
56 /**
57 * @return name of this PBKDF
58 */
59 virtual std::string name() const = 0;
60
61 virtual ~PBKDF() = default;
62
63 /**
64 * Derive a key from a passphrase for a number of iterations
65 * specified by either iterations or if iterations == 0 then
66 * running until msec time has elapsed.
67 *
68 * @param out buffer to store the derived key, must be of out_len bytes
69 * @param out_len the desired length of the key to produce
70 * @param passphrase the password to derive the key from
71 * @param salt a randomly chosen salt
72 * @param salt_len length of salt in bytes
73 * @param iterations the number of iterations to use (use 10K or more)
74 * @param msec if iterations is zero, then instead the PBKDF is
75 * run until msec milliseconds has passed.
76 * @return the number of iterations performed
77 */
78 virtual size_t pbkdf(uint8_t out[], size_t out_len,
79 const std::string& passphrase,
80 const uint8_t salt[], size_t salt_len,
81 size_t iterations,
82 std::chrono::milliseconds msec) const = 0;
83
84 /**
85 * Derive a key from a passphrase for a number of iterations.
86 *
87 * @param out buffer to store the derived key, must be of out_len bytes
88 * @param out_len the desired length of the key to produce
89 * @param passphrase the password to derive the key from
90 * @param salt a randomly chosen salt
91 * @param salt_len length of salt in bytes
92 * @param iterations the number of iterations to use (use 10K or more)
93 */
94 void pbkdf_iterations(uint8_t out[], size_t out_len,
95 const std::string& passphrase,
96 const uint8_t salt[], size_t salt_len,
97 size_t iterations) const;
98
99 /**
100 * Derive a key from a passphrase, running until msec time has elapsed.
101 *
102 * @param out buffer to store the derived key, must be of out_len bytes
103 * @param out_len the desired length of the key to produce
104 * @param passphrase the password to derive the key from
105 * @param salt a randomly chosen salt
106 * @param salt_len length of salt in bytes
107 * @param msec if iterations is zero, then instead the PBKDF is
108 * run until msec milliseconds has passed.
109 * @param iterations set to the number iterations executed
110 */
111 void pbkdf_timed(uint8_t out[], size_t out_len,
112 const std::string& passphrase,
113 const uint8_t salt[], size_t salt_len,
114 std::chrono::milliseconds msec,
115 size_t& iterations) const;
116
117 /**
118 * Derive a key from a passphrase for a number of iterations.
119 *
120 * @param out_len the desired length of the key to produce
121 * @param passphrase the password to derive the key from
122 * @param salt a randomly chosen salt
123 * @param salt_len length of salt in bytes
124 * @param iterations the number of iterations to use (use 10K or more)
125 * @return the derived key
126 */
127 secure_vector<uint8_t> pbkdf_iterations(size_t out_len,
128 const std::string& passphrase,
129 const uint8_t salt[], size_t salt_len,
130 size_t iterations) const;
131
132 /**
133 * Derive a key from a passphrase, running until msec time has elapsed.
134 *
135 * @param out_len the desired length of the key to produce
136 * @param passphrase the password to derive the key from
137 * @param salt a randomly chosen salt
138 * @param salt_len length of salt in bytes
139 * @param msec if iterations is zero, then instead the PBKDF is
140 * run until msec milliseconds has passed.
141 * @param iterations set to the number iterations executed
142 * @return the derived key
143 */
144 secure_vector<uint8_t> pbkdf_timed(size_t out_len,
145 const std::string& passphrase,
146 const uint8_t salt[], size_t salt_len,
147 std::chrono::milliseconds msec,
148 size_t& iterations) const;
149
150 // Following kept for compat with 1.10:
151
152 /**
153 * Derive a key from a passphrase
154 * @param out_len the desired length of the key to produce
155 * @param passphrase the password to derive the key from
156 * @param salt a randomly chosen salt
157 * @param salt_len length of salt in bytes
158 * @param iterations the number of iterations to use (use 10K or more)
159 */
160 OctetString derive_key(size_t out_len,
161 const std::string& passphrase,
162 const uint8_t salt[], size_t salt_len,
163 size_t iterations) const
164 {
165 return pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations);
166 }
167
168 /**
169 * Derive a key from a passphrase
170 * @param out_len the desired length of the key to produce
171 * @param passphrase the password to derive the key from
172 * @param salt a randomly chosen salt
173 * @param iterations the number of iterations to use (use 10K or more)
174 */
175 template<typename Alloc>
176 OctetString derive_key(size_t out_len,
177 const std::string& passphrase,
178 const std::vector<uint8_t, Alloc>& salt,
179 size_t iterations) const
180 {
181 return pbkdf_iterations(out_len, passphrase, salt.data(), salt.size(), iterations);
182 }
183
184 /**
185 * Derive a key from a passphrase
186 * @param out_len the desired length of the key to produce
187 * @param passphrase the password to derive the key from
188 * @param salt a randomly chosen salt
189 * @param salt_len length of salt in bytes
190 * @param msec is how long to run the PBKDF
191 * @param iterations is set to the number of iterations used
192 */
193 OctetString derive_key(size_t out_len,
194 const std::string& passphrase,
195 const uint8_t salt[], size_t salt_len,
196 std::chrono::milliseconds msec,
197 size_t& iterations) const
198 {
199 return pbkdf_timed(out_len, passphrase, salt, salt_len, msec, iterations);
200 }
201
202 /**
203 * Derive a key from a passphrase using a certain amount of time
204 * @param out_len the desired length of the key to produce
205 * @param passphrase the password to derive the key from
206 * @param salt a randomly chosen salt
207 * @param msec is how long to run the PBKDF
208 * @param iterations is set to the number of iterations used
209 */
210 template<typename Alloc>
211 OctetString derive_key(size_t out_len,
212 const std::string& passphrase,
213 const std::vector<uint8_t, Alloc>& salt,
214 std::chrono::milliseconds msec,
215 size_t& iterations) const
216 {
217 return pbkdf_timed(out_len, passphrase, salt.data(), salt.size(), msec, iterations);
218 }
219 };
220
221 /*
222 * Compatibility typedef
223 */
224 typedef PBKDF S2K;
225
226 /**
227 * Password based key derivation function factory method
228 * @param algo_spec the name of the desired PBKDF algorithm
229 * @param provider the provider to use
230 * @return pointer to newly allocated object of that type
231 */
232 inline PBKDF* get_pbkdf(const std::string& algo_spec,
233 const std::string& provider = "")
234 {
235 return PBKDF::create_or_throw(algo_spec, provider).release();
236 }
237
238 inline PBKDF* get_s2k(const std::string& algo_spec)
239 {
240 return get_pbkdf(algo_spec);
241 }
242
243
244 }
245
246 #endif
Botan::OctetString
Definition: symkey.h:19
Botan::PBKDF::derive_key
OctetString derive_key(size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, std::chrono::milliseconds msec, size_t &iterations) const
Definition: pbkdf.h:193
Botan::PBKDF::derive_key
OctetString derive_key(size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const
Definition: pbkdf.h:160
BOTAN_PUBLIC_API
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
Botan::S2K
PBKDF S2K
Definition: pbkdf.h:224
Botan::get_s2k
PBKDF * get_s2k(const std::string &algo_spec)
Definition: pbkdf.h:238
name
std::string name
Definition: commoncrypto_hash.cpp:23
Botan::secure_vector
std::vector< T, secure_allocator< T >> secure_vector
Definition: secmem.h:65
Botan::PBKDF::derive_key
OctetString derive_key(size_t out_len, const std::string &passphrase, const std::vector< uint8_t, Alloc > &salt, size_t iterations) const
Definition: pbkdf.h:176
Botan::get_pbkdf
PBKDF * get_pbkdf(const std::string &algo_spec, const std::string &provider="")
Definition: pbkdf.h:232
salt_len
size_t salt_len
Definition: x509_obj.cpp:25
Botan
Definition: alg_id.cpp:13
Botan::PBKDF::create_or_throw
static std::unique_ptr< PBKDF > create_or_throw(const std::string &algo_spec, const std::string &provider="")
Definition: pbkdf.cpp:74
Botan::PBKDF::derive_key
OctetString derive_key(size_t out_len, const std::string &passphrase, const std::vector< uint8_t, Alloc > &salt, std::chrono::milliseconds msec, size_t &iterations) const
Definition: pbkdf.h:211
Botan::PBKDF
Definition: pbkdf.h:24