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