/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>

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(const std::string& algo_spec,
                                           const std::string& 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(const std::string& algo_spec,
                         const std::string& provider = "");

      /**
      * @return list of available providers for this algorithm, empty if not available
      */
      static std::vector<std::string> providers(const std::string& 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,
                           const std::string& 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,
                            const std::string& 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,
                         const std::string& 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,
                                           const std::string& 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,
                                      const std::string& 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,
                             const std::string& passphrase,
                             const uint8_t salt[], size_t salt_len,
                             size_t iterations) const
         {
         return 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,
                             const std::string& passphrase,
                             const std::vector<uint8_t, Alloc>& salt,
                             size_t iterations) const
         {
         return 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,
                             const std::string& passphrase,
                             const uint8_t salt[], size_t salt_len,
                             std::chrono::milliseconds msec,
                             size_t& iterations) const
         {
         return 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,
                             const std::string& passphrase,
                             const std::vector<uint8_t, Alloc>& salt,
                             std::chrono::milliseconds msec,
                             size_t& iterations) const
         {
         return 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
*/
inline PBKDF* get_pbkdf(const std::string& algo_spec,
                        const std::string& provider = "")
   {
   return PBKDF::create_or_throw(algo_spec, provider).release();
   }

inline PBKDF* get_s2k(const std::string& algo_spec)
   {
   return get_pbkdf(algo_spec);
   }


}

#endif

Coverage Report

Created: 2022-05-14 06:06

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