Botan 2.1.0 Crypto and TLS for C++11

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

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
Botan::PBKDF::create
static std::unique_ptr< PBKDF > create(const std::string &algo_spec, const std::string &provider="")
Definition: pbkdf.cpp:21
Botan::OctetString
Definition: symkey.h:19
Botan::PBKDF::derive_key
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
Botan::PBKDF::derive_key
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
Botan::secure_vector
std::vector< T, secure_allocator< T >> secure_vector
Definition: secmem.h:121
Botan::PBKDF::derive_key
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
Botan::get_pbkdf
PBKDF * get_pbkdf(const std::string &algo_spec, const std::string &provider="")
Definition: pbkdf.h:216
Botan
Definition: alg_id.cpp:13
Botan::PBKDF::derive_key
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
Botan::Algorithm_Not_Found
Definition: exceptn.h:140
Botan::PBKDF
Definition: pbkdf.h:22