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