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