12805544433

Committed 16 Jan 2025 09:08AM UTC coverage: 90.876% (-0.4%) from 91.245%

Build # 12805544433

Build Type

Pull #4540

github

Committed by

web-flow

Commit Message

Merge cc1ceff51 into 9b798efbb

Pull Request Pull Request #4540: PKCS #11 Version 3.2 Support

Run Details

93425 of 102805 relevant lines covered (90.88%)

11409241.89 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

95.0

/src/lib/kdf/kdf.h

/*
* Key Derivation Function interfaces
* (C) 1999-2007 Jack Lloyd
* (C) 2024      René Meusel - Rohde & Schwarz Cybersecurity
*
* 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
      */
      BOTAN_DEPRECATED("Use KDF::derive_key")
      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 {
         derive_key({key, key_len}, {secret, secret_len}, {salt, salt_len}, {label, label_len});
      }

      /**
      * 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>>
      BOTAN_DEPRECATED("Use std::span or std::string_view overloads")
      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 {
         return derive_key<T>(key_len, {secret, secret_len}, {salt, salt_len}, {label, label_len});
      }

      /**
      * 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,
                              {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 {
         perform_kdf(key, secret, salt, label);
      }

      /**
      * 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 {
         T key(key_len);
         perform_kdf(key, secret, salt, label);
         return key;
      }

      /**
      * 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>>
      BOTAN_DEPRECATED("Use std::span or std::string_view overloads")
      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, {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>>
      BOTAN_DEPRECATED("Use std::span or std::string_view overloads")
      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()});
      }

      /**
      * Derive a key
      * @tparam 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 <size_t key_len>
      std::array<uint8_t, key_len> derive_key(std::span<const uint8_t> secret,
                                              std::span<const uint8_t> salt = {},
                                              std::span<const uint8_t> label = {}) {
         std::array<uint8_t, key_len> key;
         perform_kdf(key, secret, salt, label);
         return key;
      }

      /**
      * Derive a key
      * @tparam 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 <size_t key_len>
      std::array<uint8_t, key_len> derive_key(std::span<const uint8_t> secret,
                                              std::span<const uint8_t> salt = {},
                                              std::string_view label = "") {
         return derive_key<key_len>(secret, salt, {cast_char_ptr_to_uint8(label.data()), label.size()});
      }

      /**
      * Derive a key
      * @tparam 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 <size_t key_len>
      std::array<uint8_t, key_len> derive_key(std::span<const uint8_t> secret,
                                              std::string_view salt = "",
                                              std::string_view label = "") {
         return derive_key<key_len>(secret,
                                    {cast_char_ptr_to_uint8(salt.data()), salt.size()},
                                    {cast_char_ptr_to_uint8(label.data()), label.size()});
      }

      /**
      * @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(); }

   protected:
      /**
      * Internal customization point for subclasses
      *
      * The byte size of the @p key span is the number of bytes to be produced
      * by the concrete key derivation function.
      *
      * @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
      */
      virtual void perform_kdf(std::span<uint8_t> key,
                               std::span<const uint8_t> secret,
                               std::span<const uint8_t> salt,
                               std::span<const uint8_t> label) const = 0;
};

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

1	/*
2	* Key Derivation Function interfaces
3	* (C) 1999-2007 Jack Lloyd
4	* (C) 2024 René Meusel - Rohde & Schwarz Cybersecurity
5	*
6	* Botan is released under the Simplified BSD License (see license.txt)
7	*/
8
9	#ifndef BOTAN_KDF_BASE_H_
10	#define BOTAN_KDF_BASE_H_
11
12	#include <botan/concepts.h>
13	#include <botan/exceptn.h>
14	#include <botan/mem_ops.h>
15	#include <botan/secmem.h>
16	#include <span>
17	#include <string>
18	#include <string_view>
19
20	namespace Botan {
21
22	/**
23	* Key Derivation Function
24	*/
25	class BOTAN_PUBLIC_API(2, 0) KDF {	11,065✔
26	public:
27	virtual ~KDF() = default;	30✔
28
29	/**
30	* Create an instance based on a name
31	* If provider is empty then best available is chosen.
32	* @param algo_spec algorithm name
33	* @param provider provider implementation to choose
34	* @return a null pointer if the algo/provider combination cannot be found
35	*/
36	static std::unique_ptr<KDF> create(std::string_view algo_spec, std::string_view provider = "");
37
38	/**
39	* Create an instance based on a name, or throw if the
40	* algo/provider combination cannot be found. If provider is
41	* empty then best available is chosen.
42	*/
43	static std::unique_ptr<KDF> create_or_throw(std::string_view algo_spec, std::string_view provider = "");
44
45	/**
46	* @return list of available providers for this algorithm, empty if not available
47	*/
48	static std::vector<std::string> providers(std::string_view algo_spec);
49
50	/**
51	* @return KDF name
52	*/
53	virtual std::string name() const = 0;
54
55	/**
56	* Derive a key
57	* @param key buffer holding the derived key, must be of length key_len
58	* @param key_len the desired output length in bytes
59	* @param secret the secret input
60	* @param secret_len size of secret in bytes
61	* @param salt a diversifier
62	* @param salt_len size of salt in bytes
63	* @param label purpose for the derived keying material
64	* @param label_len size of label in bytes
65	*/
66	BOTAN_DEPRECATED("Use KDF::derive_key")
67	void kdf(uint8_t key[],	2✔
68	size_t key_len,
69	const uint8_t secret[],
70	size_t secret_len,
71	const uint8_t salt[],
72	size_t salt_len,
73	const uint8_t label[],
74	size_t label_len) const {
75	derive_key({key, key_len}, {secret, secret_len}, {salt, salt_len}, {label, label_len});	2✔
76	}
77
78	/**
79	* Derive a key
80	* @param key_len the desired output length in bytes
81	* @param secret the secret input
82	* @param secret_len size of secret in bytes
83	* @param salt a diversifier
84	* @param salt_len size of salt in bytes
85	* @param label purpose for the derived keying material
86	* @param label_len size of label in bytes
87	* @return the derived key
88	*/
89	template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
90	BOTAN_DEPRECATED("Use std::span or std::string_view overloads")
91	T derive_key(size_t key_len,	1,893✔
92	const uint8_t secret[],
93	size_t secret_len,
94	const uint8_t salt[],
95	size_t salt_len,
96	const uint8_t label[] = nullptr,
97	size_t label_len = 0) const {
98	return derive_key<T>(key_len, {secret, secret_len}, {salt, salt_len}, {label, label_len});	1,893✔
99	}
100
101	/**
102	* Derive a key
103	* @param key_len the desired output length in bytes
104	* @param secret the secret input
105	* @param salt a diversifier
106	* @param label purpose for the derived keying material
107	* @return the derived key
108	*/
109	template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
110	T derive_key(size_t key_len,	1,898✔
111	std::span<const uint8_t> secret,
112	std::string_view salt = "",
113	std::string_view label = "") const {
114	return derive_key<T>(key_len,
115	secret,
116	{cast_char_ptr_to_uint8(salt.data()), salt.length()},
117	{cast_char_ptr_to_uint8(label.data()), label.length()});	1,898✔
118	}
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,	5,293✔
128	std::span<const uint8_t> secret,
129	std::span<const uint8_t> salt,
130	std::span<const uint8_t> label) const {
131	perform_kdf(key, secret, salt, label);	5,293✔
132	}	5,291✔
133
134	/**
135	* Derive a key
136	* @param key_len the desired output length in bytes
137	* @param secret the secret input
138	* @param salt a diversifier
139	* @param label purpose for the derived keying material
140	* @return the derived key
141	*/
142	template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
143	T derive_key(size_t key_len,	28,471✔
144	std::span<const uint8_t> secret,
145	std::span<const uint8_t> salt,
146	std::span<const uint8_t> label) const {
147	T key(key_len);	28,471✔
148	perform_kdf(key, secret, salt, label);	28,471✔
149	return key;	28,471✔
150	}	×
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	BOTAN_DEPRECATED("Use std::span or std::string_view overloads")
163	T derive_key(size_t key_len,	48✔
164	std::span<const uint8_t> secret,
165	const uint8_t salt[],
166	size_t salt_len,
167	std::string_view label = "") const {
168	return derive_key<T>(key_len, secret, {salt, salt_len}, {cast_char_ptr_to_uint8(label.data()), label.size()});	48✔
169	}
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	BOTAN_DEPRECATED("Use std::span or std::string_view overloads")
182	T derive_key(size_t key_len,
183	const uint8_t secret[],
184	size_t secret_len,
185	std::string_view salt = "",
186	std::string_view label = "") const {
187	return derive_key<T>(key_len,
188	{secret, secret_len},
189	{cast_char_ptr_to_uint8(salt.data()), salt.length()},
190	{cast_char_ptr_to_uint8(label.data()), label.length()});
191	}
192
193	/**
194	* Derive a key
195	* @tparam key_len the desired output length in bytes
196	* @param secret the secret input
197	* @param salt a diversifier
198	* @param label purpose for the derived keying material
199	* @return the derived key
200	*/
201	template <size_t key_len>
202	std::array<uint8_t, key_len> derive_key(std::span<const uint8_t> secret,	26✔
203	std::span<const uint8_t> salt = {},
204	std::span<const uint8_t> label = {}) {
205	std::array<uint8_t, key_len> key;
206	perform_kdf(key, secret, salt, label);	26✔
207	return key;
208	}
209
210	/**
211	* Derive a key
212	* @tparam key_len the desired output length in bytes
213	* @param secret the secret input
214	* @param salt a diversifier
215	* @param label purpose for the derived keying material
216	* @return the derived key
217	*/
218	template <size_t key_len>
219	std::array<uint8_t, key_len> derive_key(std::span<const uint8_t> secret,
220	std::span<const uint8_t> salt = {},
221	std::string_view label = "") {
222	return derive_key<key_len>(secret, salt, {cast_char_ptr_to_uint8(label.data()), label.size()});
223	}
224
225	/**
226	* Derive a key
227	* @tparam key_len the desired output length in bytes
228	* @param secret the secret input
229	* @param salt a diversifier
230	* @param label purpose for the derived keying material
231	* @return the derived key
232	*/
233	template <size_t key_len>
234	std::array<uint8_t, key_len> derive_key(std::span<const uint8_t> secret,
235	std::string_view salt = "",
236	std::string_view label = "") {
237	return derive_key<key_len>(secret,
238	{cast_char_ptr_to_uint8(salt.data()), salt.size()},
239	{cast_char_ptr_to_uint8(label.data()), label.size()});
240	}
241
242	/**
243	* @return new object representing the same algorithm as *this
244	*/
245	virtual std::unique_ptr<KDF> new_object() const = 0;
246
247	/**
248	* @return new object representing the same algorithm as *this
249	*/
250	KDF* clone() const { return this->new_object().release(); }
251
252	protected:
253	/**
254	* Internal customization point for subclasses
255	*
256	* The byte size of the @p key span is the number of bytes to be produced
257	* by the concrete key derivation function.
258	*
259	* @param key the output buffer for the to-be-derived key
260	* @param secret the secret input
261	* @param salt a diversifier
262	* @param label purpose for the derived keying material
263	*/
264	virtual void perform_kdf(std::span<uint8_t> key,
265	std::span<const uint8_t> secret,
266	std::span<const uint8_t> salt,
267	std::span<const uint8_t> label) const = 0;
268	};
269
270	/**
271	* Factory method for KDF (key derivation function)
272	* @param algo_spec the name of the KDF to create
273	* @return pointer to newly allocated object of that type
274	*
275	* Prefer KDF::create
276	*/
277	BOTAN_DEPRECATED("Use KDF::create")
278
279	inline KDF* get_kdf(std::string_view algo_spec) {
280	auto kdf = KDF::create(algo_spec);
281	if(kdf) {
282	return kdf.release();
283	}
284
285	if(algo_spec == "Raw") {
286	return nullptr;
287	}
288
289	throw Algorithm_Not_Found(algo_spec);
290	}
291
292	} // namespace Botan
293
294	#endif

randombit / botan / 12805544433

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous