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

Source (jump to first uncovered line)
/*
* Key Derivation Function interfaces
* (C) 1999-2007 Jack Lloyd
*
* Botan is released under the Simplified BSD License (see license.txt)
*/

#ifndef BOTAN_KDF_BASE_H_
#define BOTAN_KDF_BASE_H_

#include <botan/concepts.h>
#include <botan/exceptn.h>
#include <botan/mem_ops.h>
#include <botan/secmem.h>
#include <span>
#include <string>
#include <string_view>

namespace Botan {

/**
* Key Derivation Function
*/
class BOTAN_PUBLIC_API(2, 0) KDF {
   public:
      virtual ~KDF() = default;

      /**
      * 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<KDF> 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<KDF> 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 KDF name
      */
      virtual std::string name() const = 0;

      /**
      * Derive a key
      * @param key buffer holding the derived key, must be of length key_len
      * @param key_len the desired output length in bytes
      * @param secret the secret input
      * @param secret_len size of secret in bytes
      * @param salt a diversifier
      * @param salt_len size of salt in bytes
      * @param label purpose for the derived keying material
      * @param label_len size of label in bytes
      */
      virtual void kdf(uint8_t key[],
                       size_t key_len,
                       const uint8_t secret[],
                       size_t secret_len,
                       const uint8_t salt[],
                       size_t salt_len,
                       const uint8_t label[],
                       size_t label_len) const = 0;

      /**
      * Derive a key
      * @param key_len the desired output length in bytes
      * @param secret the secret input
      * @param secret_len size of secret in bytes
      * @param salt a diversifier
      * @param salt_len size of salt in bytes
      * @param label purpose for the derived keying material
      * @param label_len size of label in bytes
      * @return the derived key
      */
      template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
      T derive_key(size_t key_len,
                   const uint8_t secret[],
                   size_t secret_len,
                   const uint8_t salt[],
                   size_t salt_len,
                   const uint8_t label[] = nullptr,
                   size_t label_len = 0) const {
         T key(key_len);
         kdf(key.data(), key.size(), secret, secret_len, salt, salt_len, label, label_len);
         return key;
      }

      /**
      * Derive a key
      * @param key_len the desired output length in bytes
      * @param secret the secret input
      * @param salt a diversifier
      * @param label purpose for the derived keying material
      * @return the derived key
      */
      template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
      T derive_key(size_t key_len,
                   std::span<const uint8_t> secret,
                   std::string_view salt = "",
                   std::string_view label = "") const {
         return derive_key<T>(key_len,
                              secret.data(),
                              secret.size(),
                              cast_char_ptr_to_uint8(salt.data()),
                              salt.length(),
                              cast_char_ptr_to_uint8(label.data()),
                              label.length());
      }

      /**
      * Derive a key
      * @param key the output buffer for the to-be-derived key
      * @param secret the secret input
      * @param salt a diversifier
      * @param label purpose for the derived keying material
      */
      void derive_key(std::span<uint8_t> key,
                      std::span<const uint8_t> secret,
                      std::span<const uint8_t> salt,
                      std::span<const uint8_t> label) const {
         return kdf(
            key.data(), key.size(), secret.data(), secret.size(), salt.data(), salt.size(), label.data(), label.size());
      }

      /**
      * Derive a key
      * @param key_len the desired output length in bytes
      * @param secret the secret input
      * @param salt a diversifier
      * @param label purpose for the derived keying material
      * @return the derived key
      */
      template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
      T derive_key(size_t key_len,
                   std::span<const uint8_t> secret,
                   std::span<const uint8_t> salt,
                   std::span<const uint8_t> label) const {
         return derive_key<T>(
            key_len, secret.data(), secret.size(), salt.data(), salt.size(), label.data(), label.size());
      }

      /**
      * Derive a key
      * @param key_len the desired output length in bytes
      * @param secret the secret input
      * @param salt a diversifier
      * @param salt_len size of salt in bytes
      * @param label purpose for the derived keying material
      * @return the derived key
      */
      template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
      T derive_key(size_t key_len,
                   std::span<const uint8_t> secret,
                   const uint8_t salt[],
                   size_t salt_len,
                   std::string_view label = "") const {
         return derive_key<T>(
            key_len, secret.data(), secret.size(), salt, salt_len, cast_char_ptr_to_uint8(label.data()), label.size());
      }

      /**
      * Derive a key
      * @param key_len the desired output length in bytes
      * @param secret the secret input
      * @param secret_len size of secret in bytes
      * @param salt a diversifier
      * @param label purpose for the derived keying material
      * @return the derived key
      */
      template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
      T derive_key(size_t key_len,
                   const uint8_t secret[],
                   size_t secret_len,
                   std::string_view salt = "",
                   std::string_view label = "") const {
         return derive_key<T>(key_len,
                              secret,
                              secret_len,
                              cast_char_ptr_to_uint8(salt.data()),
                              salt.length(),
                              cast_char_ptr_to_uint8(label.data()),
                              label.length());
      }

      /**
      * @return new object representing the same algorithm as *this
      */
      virtual std::unique_ptr<KDF> new_object() const = 0;

      /**
      * @return new object representing the same algorithm as *this
      */
      KDF* clone() const { return this->new_object().release(); }
};

/**
* Factory method for KDF (key derivation function)
* @param algo_spec the name of the KDF to create
* @return pointer to newly allocated object of that type
*
* Prefer KDF::create
*/
BOTAN_DEPRECATED("Use KDF::create")

inline KDF* get_kdf(std::string_view algo_spec) {
   auto kdf = KDF::create(algo_spec);
   if(kdf) {
      return kdf.release();
   }

   if(algo_spec == "Raw") {
      return nullptr;
   }

   throw Algorithm_Not_Found(algo_spec);
}

}  // namespace Botan

#endif

Coverage Report

Created: 2024-11-29 06:10

Line	Count	Source (jump to first uncovered line)
1		/*
2		* Key Derivation Function interfaces
3		* (C) 1999-2007 Jack Lloyd
4		*
5		* Botan is released under the Simplified BSD License (see license.txt)
6		*/
7
8		#ifndef BOTAN_KDF_BASE_H_
9		#define BOTAN_KDF_BASE_H_
10
11		#include <botan/concepts.h>
12		#include <botan/exceptn.h>
13		#include <botan/mem_ops.h>
14		#include <botan/secmem.h>
15		#include <span>
16		#include <string>
17		#include <string_view>
18
19		namespace Botan {
20
21		/**
22		* Key Derivation Function
23		*/
24		class BOTAN_PUBLIC_API(2, 0) KDF {
25		public:
26	2.86k	virtual ~KDF() = default;
27
28		/**
29		* Create an instance based on a name
30		* If provider is empty then best available is chosen.
31		* @param algo_spec algorithm name
32		* @param provider provider implementation to choose
33		* @return a null pointer if the algo/provider combination cannot be found
34		*/
35		static std::unique_ptr<KDF> create(std::string_view algo_spec, std::string_view 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<KDF> create_or_throw(std::string_view algo_spec, std::string_view provider = "");
43
44		/**
45		* @return list of available providers for this algorithm, empty if not available
46		*/
47		static std::vector<std::string> providers(std::string_view algo_spec);
48
49		/**
50		* @return KDF name
51		*/
52		virtual std::string name() const = 0;
53
54		/**
55		* Derive a key
56		* @param key buffer holding the derived key, must be of length key_len
57		* @param key_len the desired output length in bytes
58		* @param secret the secret input
59		* @param secret_len size of secret in bytes
60		* @param salt a diversifier
61		* @param salt_len size of salt in bytes
62		* @param label purpose for the derived keying material
63		* @param label_len size of label in bytes
64		*/
65		virtual void kdf(uint8_t key[],
66		size_t key_len,
67		const uint8_t secret[],
68		size_t secret_len,
69		const uint8_t salt[],
70		size_t salt_len,
71		const uint8_t label[],
72		size_t label_len) const = 0;
73
74		/**
75		* Derive a key
76		* @param key_len the desired output length in bytes
77		* @param secret the secret input
78		* @param secret_len size of secret in bytes
79		* @param salt a diversifier
80		* @param salt_len size of salt in bytes
81		* @param label purpose for the derived keying material
82		* @param label_len size of label in bytes
83		* @return the derived key
84		*/
85		template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
86		T derive_key(size_t key_len,
87		const uint8_t secret[],
88		size_t secret_len,
89		const uint8_t salt[],
90		size_t salt_len,
91		const uint8_t label[] = nullptr,
92	5.57k	size_t label_len = 0) const {
93	5.57k	T key(key_len);
94	5.57k	kdf(key.data(), key.size(), secret, secret_len, salt, salt_len, label, label_len);
95	5.57k	return key;
96	5.57k	}
97
98		/**
99		* Derive a key
100		* @param key_len the desired output length in bytes
101		* @param secret the secret input
102		* @param salt a diversifier
103		* @param label purpose for the derived keying material
104		* @return the derived key
105		*/
106		template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
107		T derive_key(size_t key_len,
108		std::span<const uint8_t> secret,
109		std::string_view salt = "",
110	0	std::string_view label = "") const {
111	0	return derive_key<T>(key_len,
112	0	secret.data(),
113	0	secret.size(),
114	0	cast_char_ptr_to_uint8(salt.data()),
115	0	salt.length(),
116	0	cast_char_ptr_to_uint8(label.data()),
117	0	label.length());
118	0	}
119
120		/**
121		* Derive a key
122		* @param key the output buffer for the to-be-derived key
123		* @param secret the secret input
124		* @param salt a diversifier
125		* @param label purpose for the derived keying material
126		*/
127		void derive_key(std::span<uint8_t> key,
128		std::span<const uint8_t> secret,
129		std::span<const uint8_t> salt,
130	0	std::span<const uint8_t> label) const {
131	0	return kdf(
132	0	key.data(), key.size(), secret.data(), secret.size(), salt.data(), salt.size(), label.data(), label.size());
133	0	}
134
135		/**
136		* Derive a key
137		* @param key_len the desired output length in bytes
138		* @param secret the secret input
139		* @param salt a diversifier
140		* @param label purpose for the derived keying material
141		* @return the derived key
142		*/
143		template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
144		T derive_key(size_t key_len,
145		std::span<const uint8_t> secret,
146		std::span<const uint8_t> salt,
147	2.86k	std::span<const uint8_t> label) const {
148	2.86k	return derive_key<T>(
149	2.86k	key_len, secret.data(), secret.size(), salt.data(), salt.size(), label.data(), label.size());
150	2.86k	}
151
152		/**
153		* Derive a key
154		* @param key_len the desired output length in bytes
155		* @param secret the secret input
156		* @param salt a diversifier
157		* @param salt_len size of salt in bytes
158		* @param label purpose for the derived keying material
159		* @return the derived key
160		*/
161		template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
162		T derive_key(size_t key_len,
163		std::span<const uint8_t> secret,
164		const uint8_t salt[],
165		size_t salt_len,
166	0	std::string_view label = "") const {
167	0	return derive_key<T>(
168	0	key_len, secret.data(), secret.size(), salt, salt_len, cast_char_ptr_to_uint8(label.data()), label.size());
169	0	}
170
171		/**
172		* Derive a key
173		* @param key_len the desired output length in bytes
174		* @param secret the secret input
175		* @param secret_len size of secret in bytes
176		* @param salt a diversifier
177		* @param label purpose for the derived keying material
178		* @return the derived key
179		*/
180		template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
181		T derive_key(size_t key_len,
182		const uint8_t secret[],
183		size_t secret_len,
184		std::string_view salt = "",
185		std::string_view label = "") const {
186		return derive_key<T>(key_len,
187		secret,
188		secret_len,
189		cast_char_ptr_to_uint8(salt.data()),
190		salt.length(),
191		cast_char_ptr_to_uint8(label.data()),
192		label.length());
193		}
194
195		/**
196		* @return new object representing the same algorithm as *this
197		*/
198		virtual std::unique_ptr<KDF> new_object() const = 0;
199
200		/**
201		* @return new object representing the same algorithm as *this
202		*/
203	0	KDF* clone() const { return this->new_object().release(); }
204		};
205
206		/**
207		* Factory method for KDF (key derivation function)
208		* @param algo_spec the name of the KDF to create
209		* @return pointer to newly allocated object of that type
210		*
211		* Prefer KDF::create
212		*/
213		BOTAN_DEPRECATED("Use KDF::create")
214
215	0	inline KDF* get_kdf(std::string_view algo_spec) {
216	0	auto kdf = KDF::create(algo_spec);
217	0	if(kdf) {
218	0	return kdf.release();
219	0	}
220	0
221	0	if(algo_spec == "Raw") {
222	0	return nullptr;
223	0	}
224	0
225	0	throw Algorithm_Not_Found(algo_spec);
226	0	}
227
228		} // namespace Botan
229
230		#endif