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