/src/botan/build/include/public/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
      */
      BOTAN_DEPRECATED("Use PasswordHashFamily + PasswordHash")
      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.
      */
      BOTAN_DEPRECATED("Use PasswordHashFamily + PasswordHash")
      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 PasswordHashFamily + PasswordHash")
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 PasswordHashFamily + PasswordHash") inline PBKDF* get_s2k(std::string_view algo_spec) {
   return PBKDF::create_or_throw(algo_spec).release();
}

}  // namespace Botan

#endif

Coverage Report

Created: 2024-11-21 07:03

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