Botan 3.3.0
Crypto and TLS for C&
kdf.h
Go to the documentation of this file.
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
19namespace Botan {
20
21/**
22* Key Derivation Function
23*/
24class BOTAN_PUBLIC_API(2, 0) KDF {
25 public:
26 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 size_t label_len = 0) const {
93 T key(key_len);
94 kdf(key.data(), key.size(), secret, secret_len, salt, salt_len, label, label_len);
95 return key;
96 }
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 std::string_view label = "") const {
111 return derive_key<T>(key_len,
112 secret.data(),
113 secret.size(),
114 cast_char_ptr_to_uint8(salt.data()),
115 salt.length(),
116 cast_char_ptr_to_uint8(label.data()),
117 label.length());
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,
128 std::span<const uint8_t> secret,
129 std::span<const uint8_t> salt,
130 std::span<const uint8_t> label) const {
131 return kdf(
132 key.data(), key.size(), secret.data(), secret.size(), salt.data(), salt.size(), label.data(), label.size());
133 }
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 std::span<const uint8_t> label) const {
148 return derive_key<T>(
149 key_len, secret.data(), secret.size(), salt.data(), salt.size(), label.data(), label.size());
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 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 std::string_view label = "") const {
167 return derive_key<T>(
168 key_len, secret.data(), secret.size(), salt, salt_len, cast_char_ptr_to_uint8(label.data()), label.size());
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 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 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*/
213BOTAN_DEPRECATED("Use KDF::create")
214
215inline KDF* get_kdf(std::string_view algo_spec) {
216 auto kdf = KDF::create(algo_spec);
217 if(kdf) {
218 return kdf.release();
219 }
220
221 if(algo_spec == "Raw") {
222 return nullptr;
223 }
224
225 throw Algorithm_Not_Found(algo_spec);
226}
227
228} // namespace Botan
229
230#endif
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
Definition kdf.h:127
virtual std::unique_ptr< KDF > new_object() const =0
T derive_key(size_t key_len, std::span< const uint8_t > secret, std::string_view salt="", std::string_view label="") const
Definition kdf.h:107
static std::unique_ptr< KDF > create(std::string_view algo_spec, std::string_view provider="")
Definition kdf.cpp:71
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
T derive_key(size_t key_len, const uint8_t secret[], size_t secret_len, std::string_view salt="", std::string_view label="") const
Definition kdf.h:181
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
Definition kdf.h:86
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
Definition kdf.h:162
virtual std::string name() const =0
virtual ~KDF()=default
KDF * clone() const
Definition kdf.h:203
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
Definition kdf.h:144
#define BOTAN_PUBLIC_API(maj, min)
Definition compiler.h:31
#define BOTAN_DEPRECATED(msg)
Definition compiler.h:125
FE_25519 T
Definition ge.cpp:34
KDF * get_kdf(std::string_view algo_spec)
Definition kdf.h:215
const uint8_t * cast_char_ptr_to_uint8(const char *s)
Definition mem_ops.h:272