Coverage Report

Created: 2021-05-04 09:02

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