/src/botan/build/include/botan/pbkdf.h

Source (jump to first uncovered line)
/*
* PBKDF
* (C) 1999-2007,2012,2015 Jack Lloyd
*
* Botan is released under the Simplified BSD License (see license.txt)
*/

#ifndef BOTAN_PBKDF_H_
#define BOTAN_PBKDF_H_

#include <botan/symkey.h>
#include <chrono>
#include <string>
#include <string_view>

/*
* This entire interface is deprecated. Use the interface in pwdhash.h
*/
BOTAN_DEPRECATED_HEADER("pbkdf.h")

namespace Botan {

/**
* Base class for PBKDF (password based key derivation function)
* implementations. Converts a password into a key using a salt
* and iterated hashing to make brute force attacks harder.
*
* Starting in 2.8 this functionality is also offered by PasswordHash.
* The PBKDF interface may be removed in a future release.
*/
class BOTAN_PUBLIC_API(2, 0) PBKDF {
   public:
      /**
      * Create an instance based on a name
      * If provider is empty then best available is chosen.
      * @param algo_spec algorithm name
      * @param provider provider implementation to choose
      * @return a null pointer if the algo/provider combination cannot be found
      */
      static std::unique_ptr<PBKDF> create(std::string_view algo_spec, std::string_view provider = "");

      /**
      * Create an instance based on a name, or throw if the
      * algo/provider combination cannot be found. If provider is
      * empty then best available is chosen.
      */
      static std::unique_ptr<PBKDF> create_or_throw(std::string_view algo_spec, std::string_view provider = "");

      /**
      * @return list of available providers for this algorithm, empty if not available
      */
      static std::vector<std::string> providers(std::string_view algo_spec);

      /**
      * @return new instance of this same algorithm
      */
      virtual std::unique_ptr<PBKDF> new_object() const = 0;

      /**
      * @return new instance of this same algorithm
      */
      PBKDF* clone() const { return this->new_object().release(); }

      /**
      * @return name of this PBKDF
      */
      virtual std::string name() const = 0;

      virtual ~PBKDF() = default;

      /**
      * Derive a key from a passphrase for a number of iterations
      * specified by either iterations or if iterations == 0 then
      * running until msec time has elapsed.
      *
      * @param out buffer to store the derived key, must be of out_len bytes
      * @param out_len the desired length of the key to produce
      * @param passphrase the password to derive the key from
      * @param salt a randomly chosen salt
      * @param salt_len length of salt in bytes
      * @param iterations the number of iterations to use (use 10K or more)
      * @param msec if iterations is zero, then instead the PBKDF is
      *        run until msec milliseconds has passed.
      * @return the number of iterations performed
      */
      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;

      /**
      * Derive a key from a passphrase for a number of iterations.
      *
      * @param out buffer to store the derived key, must be of out_len bytes
      * @param out_len the desired length of the key to produce
      * @param passphrase the password to derive the key from
      * @param salt a randomly chosen salt
      * @param salt_len length of salt in bytes
      * @param iterations the number of iterations to use (use 10K or more)
      */
      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;

      /**
      * Derive a key from a passphrase, running until msec time has elapsed.
      *
      * @param out buffer to store the derived key, must be of out_len bytes
      * @param out_len the desired length of the key to produce
      * @param passphrase the password to derive the key from
      * @param salt a randomly chosen salt
      * @param salt_len length of salt in bytes
      * @param msec if iterations is zero, then instead the PBKDF is
      *        run until msec milliseconds has passed.
      * @param iterations set to the number iterations executed
      */
      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;

      /**
      * Derive a key from a passphrase for a number of iterations.
      *
      * @param out_len the desired length of the key to produce
      * @param passphrase the password to derive the key from
      * @param salt a randomly chosen salt
      * @param salt_len length of salt in bytes
      * @param iterations the number of iterations to use (use 10K or more)
      * @return the derived key
      */
      secure_vector<uint8_t> pbkdf_iterations(
         size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const;

      /**
      * Derive a key from a passphrase, running until msec time has elapsed.
      *
      * @param out_len the desired length of the key to produce
      * @param passphrase the password to derive the key from
      * @param salt a randomly chosen salt
      * @param salt_len length of salt in bytes
      * @param msec if iterations is zero, then instead the PBKDF is
      *        run until msec milliseconds has passed.
      * @param iterations set to the number iterations executed
      * @return the derived key
      */
      secure_vector<uint8_t> pbkdf_timed(size_t out_len,
                                         std::string_view passphrase,
                                         const uint8_t salt[],
                                         size_t salt_len,
                                         std::chrono::milliseconds msec,
                                         size_t& iterations) const;

      // Following kept for compat with 1.10:

      /**
      * Derive a key from a passphrase
      * @param out_len the desired length of the key to produce
      * @param passphrase the password to derive the key from
      * @param salt a randomly chosen salt
      * @param salt_len length of salt in bytes
      * @param iterations the number of iterations to use (use 10K or more)
      */
      OctetString derive_key(
         size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const {
         return OctetString(pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations));
      }

      /**
      * Derive a key from a passphrase
      * @param out_len the desired length of the key to produce
      * @param passphrase the password to derive the key from
      * @param salt a randomly chosen salt
      * @param iterations the number of iterations to use (use 10K or more)
      */
      template <typename Alloc>
      OctetString derive_key(size_t out_len,
                             std::string_view passphrase,
                             const std::vector<uint8_t, Alloc>& salt,
                             size_t iterations) const {
         return OctetString(pbkdf_iterations(out_len, passphrase, salt.data(), salt.size(), iterations));
      }

      /**
      * Derive a key from a passphrase
      * @param out_len the desired length of the key to produce
      * @param passphrase the password to derive the key from
      * @param salt a randomly chosen salt
      * @param salt_len length of salt in bytes
      * @param msec is how long to run the PBKDF
      * @param iterations is set to the number of iterations used
      */
      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 {
         return OctetString(pbkdf_timed(out_len, passphrase, salt, salt_len, msec, iterations));
      }

      /**
      * Derive a key from a passphrase using a certain amount of time
      * @param out_len the desired length of the key to produce
      * @param passphrase the password to derive the key from
      * @param salt a randomly chosen salt
      * @param msec is how long to run the PBKDF
      * @param iterations is set to the number of iterations used
      */
      template <typename Alloc>
      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 {
         return OctetString(pbkdf_timed(out_len, passphrase, salt.data(), salt.size(), msec, iterations));
      }
};

/*
* Compatibility typedef
*/
typedef PBKDF S2K;

/**
* Password based key derivation function factory method
* @param algo_spec the name of the desired PBKDF algorithm
* @param provider the provider to use
* @return pointer to newly allocated object of that type
*/
BOTAN_DEPRECATED("Use PBKDF::create_or_throw")

inline PBKDF* get_pbkdf(std::string_view algo_spec, std::string_view provider = "") {
   return PBKDF::create_or_throw(algo_spec, provider).release();
}

BOTAN_DEPRECATED("Use PBKDF::create_or_throw")

inline PBKDF* get_s2k(std::string_view algo_spec) { return PBKDF::create_or_throw(algo_spec).release(); }

}  // namespace Botan

#endif

Coverage Report

Created: 2023-06-07 07:01

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		#include <string>
14		#include <string_view>
15
16		/*
17		* This entire interface is deprecated. Use the interface in pwdhash.h
18		*/
19		BOTAN_DEPRECATED_HEADER("pbkdf.h")
20
21		namespace 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		*/
31		class BOTAN_PUBLIC_API(2, 0) PBKDF {
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	0	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	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[],
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		*/
173		OctetString derive_key(
174	0	size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const {
175	0	return OctetString(pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations));
176	0	}
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	0	size_t& iterations) const {
208	0	return OctetString(pbkdf_timed(out_len, passphrase, salt, salt_len, msec, iterations));
209	0	}
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		*/
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		BOTAN_DEPRECATED("Use PBKDF::create_or_throw")
241
242	0	inline PBKDF* get_pbkdf(std::string_view algo_spec, std::string_view provider = "") {
243	0	return PBKDF::create_or_throw(algo_spec, provider).release();
244	0	}
245
246		BOTAN_DEPRECATED("Use PBKDF::create_or_throw")
247
248	0	inline PBKDF* get_s2k(std::string_view algo_spec) { return PBKDF::create_or_throw(algo_spec).release(); }
249
250		} // namespace Botan
251
252		#endif