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