Botan 2.19.2
Crypto and TLS for C&
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
14namespace 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*/
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*/
224typedef 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*/
232inline 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
238inline PBKDF* get_s2k(const std::string& algo_spec)
239 {
240 return get_pbkdf(algo_spec);
241 }
242
243
244}
245
246#endif
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
virtual size_t pbkdf(uint8_t out[], size_t out_len, const std::string &passphrase, const uint8_t salt[], size_t salt_len, size_t iterations, std::chrono::milliseconds msec) const =0
virtual ~PBKDF()=default
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
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
static std::unique_ptr< PBKDF > create_or_throw(const std::string &algo_spec, const std::string &provider="")
Definition: pbkdf.cpp:72
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
virtual PBKDF * clone() const =0
virtual std::string name() const =0
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
Definition: alg_id.cpp:13
PBKDF * get_pbkdf(const std::string &algo_spec, const std::string &provider="")
Definition: pbkdf.h:232
PBKDF S2K
Definition: pbkdf.h:224
PBKDF * get_s2k(const std::string &algo_spec)
Definition: pbkdf.h:238
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:65
size_t salt_len
Definition: x509_obj.cpp:25