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