Botan  2.11.0
Crypto and TLS for C++11
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 */
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
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
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
PBKDF S2K
Definition: pbkdf.h:224
PBKDF * get_s2k(const std::string &algo_spec)
Definition: pbkdf.h:238
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
std::string name
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
PBKDF * get_pbkdf(const std::string &algo_spec, const std::string &provider="")
Definition: pbkdf.h:232
size_t salt_len
Definition: x509_obj.cpp:26
Definition: alg_id.cpp:13
static std::unique_ptr< PBKDF > create_or_throw(const std::string &algo_spec, const std::string &provider="")
Definition: pbkdf.cpp:74
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:65