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

Source
/*
* 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 <memory>
#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.
*
* @warning
* This class will be removed in a future major release. Use PasswordHash
*/
class BOTAN_PUBLIC_API(2, 0) PBKDF /* NOLINT(*-special-member-functions) */ {
   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: 2026-06-08 07:04

Line	Count	Source
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		*/
20		BOTAN_DEPRECATED_HEADER("pbkdf.h")
21
22		namespace 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		*/
34		class 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	0	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	0	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		*/
146		secure_vector<uint8_t> pbkdf_iterations(
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		*/
178		OctetString derive_key(
179	0	size_t out_len, std::string_view passphrase, const uint8_t salt[], size_t salt_len, size_t iterations) const {
180	0	return OctetString(pbkdf_iterations(out_len, passphrase, salt, salt_len, iterations));
181	0	}
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	0	size_t& iterations) const {
213	0	return OctetString(pbkdf_timed(out_len, passphrase, salt, salt_len, msec, iterations));
214	0	}
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		*/
237		typedef 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		*/
245		BOTAN_DEPRECATED("Use PasswordHashFamily + PasswordHash")
246	0	inline PBKDF* get_pbkdf(std::string_view algo_spec, std::string_view provider = "") {
247	0	return PBKDF::create_or_throw(algo_spec, provider).release();
248	0	}
249
250	0	BOTAN_DEPRECATED("Use PasswordHashFamily + PasswordHash") inline PBKDF* get_s2k(std::string_view algo_spec) {
251	0	return PBKDF::create_or_throw(algo_spec).release();
252	0	}
253
254		} // namespace Botan
255
256		#endif