Botan 3.1.1
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/secmem.h>
14#include <span>
15#include <string>
16#include <string_view>
17
18namespace Botan {
19
20/**
21* Key Derivation Function
22*/
23class BOTAN_PUBLIC_API(2, 0) KDF {
24 public:
25 virtual ~KDF() = default;
26
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<KDF> create(std::string_view algo_spec, std::string_view provider = "");
35
36 /**
37 * Create an instance based on a name, or throw if the
38 * algo/provider combination cannot be found. If provider is
39 * empty then best available is chosen.
40 */
41 static std::unique_ptr<KDF> create_or_throw(std::string_view algo_spec, std::string_view provider = "");
42
43 /**
44 * @return list of available providers for this algorithm, empty if not available
45 */
46 static std::vector<std::string> providers(std::string_view algo_spec);
47
48 /**
49 * @return KDF name
50 */
51 virtual std::string name() const = 0;
52
53 /**
54 * Derive a key
55 * @param key buffer holding the derived key, must be of length key_len
56 * @param key_len the desired output length in bytes
57 * @param secret the secret input
58 * @param secret_len size of secret in bytes
59 * @param salt a diversifier
60 * @param salt_len size of salt in bytes
61 * @param label purpose for the derived keying material
62 * @param label_len size of label in bytes
63 */
64 virtual void kdf(uint8_t key[],
65 size_t key_len,
66 const uint8_t secret[],
67 size_t secret_len,
68 const uint8_t salt[],
69 size_t salt_len,
70 const uint8_t label[],
71 size_t label_len) const = 0;
72
73 /**
74 * Derive a key
75 * @param key_len the desired output length in bytes
76 * @param secret the secret input
77 * @param secret_len size of secret in bytes
78 * @param salt a diversifier
79 * @param salt_len size of salt in bytes
80 * @param label purpose for the derived keying material
81 * @param label_len size of label in bytes
82 * @return the derived key
83 */
84 template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
85 T derive_key(size_t key_len,
86 const uint8_t secret[],
87 size_t secret_len,
88 const uint8_t salt[],
89 size_t salt_len,
90 const uint8_t label[] = nullptr,
91 size_t label_len = 0) const {
92 T key(key_len);
93 kdf(key.data(), key.size(), secret, secret_len, salt, salt_len, label, label_len);
94 return key;
95 }
96
97 /**
98 * Derive a key
99 * @param key_len the desired output length in bytes
100 * @param secret the secret input
101 * @param salt a diversifier
102 * @param label purpose for the derived keying material
103 * @return the derived key
104 */
105 template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
106 T derive_key(size_t key_len,
107 std::span<const uint8_t> secret,
108 std::string_view salt = "",
109 std::string_view label = "") const {
110 return derive_key<T>(key_len,
111 secret.data(),
112 secret.size(),
113 cast_char_ptr_to_uint8(salt.data()),
114 salt.length(),
115 cast_char_ptr_to_uint8(label.data()),
116 label.length());
117 }
118
119 /**
120 * Derive a key
121 * @param key_len the desired output length in bytes
122 * @param secret the secret input
123 * @param salt a diversifier
124 * @param label purpose for the derived keying material
125 * @return the derived key
126 */
127 template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
128 T derive_key(size_t key_len,
129 std::span<const uint8_t> secret,
130 std::span<const uint8_t> salt,
131 std::span<const uint8_t> label) const {
132 return derive_key<T>(
133 key_len, secret.data(), secret.size(), salt.data(), salt.size(), label.data(), label.size());
134 }
135
136 /**
137 * Derive a key
138 * @param key_len the desired output length in bytes
139 * @param secret the secret input
140 * @param salt a diversifier
141 * @param salt_len size of salt in bytes
142 * @param label purpose for the derived keying material
143 * @return the derived key
144 */
145 template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
146 T derive_key(size_t key_len,
147 std::span<const uint8_t> secret,
148 const uint8_t salt[],
149 size_t salt_len,
150 std::string_view label = "") const {
151 return derive_key<T>(
152 key_len, secret.data(), secret.size(), salt, salt_len, cast_char_ptr_to_uint8(label.data()), label.size());
153 }
154
155 /**
156 * Derive a key
157 * @param key_len the desired output length in bytes
158 * @param secret the secret input
159 * @param secret_len size of secret in bytes
160 * @param salt a diversifier
161 * @param label purpose for the derived keying material
162 * @return the derived key
163 */
164 template <concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
165 T derive_key(size_t key_len,
166 const uint8_t secret[],
167 size_t secret_len,
168 std::string_view salt = "",
169 std::string_view label = "") const {
170 return derive_key<T>(key_len,
171 secret,
172 secret_len,
173 cast_char_ptr_to_uint8(salt.data()),
174 salt.length(),
175 cast_char_ptr_to_uint8(label.data()),
176 label.length());
177 }
178
179 /**
180 * @return new object representing the same algorithm as *this
181 */
182 virtual std::unique_ptr<KDF> new_object() const = 0;
183
184 /**
185 * @return new object representing the same algorithm as *this
186 */
187 KDF* clone() const { return this->new_object().release(); }
188};
189
190/**
191* Factory method for KDF (key derivation function)
192* @param algo_spec the name of the KDF to create
193* @return pointer to newly allocated object of that type
194*
195* Prefer KDF::create
196*/
197BOTAN_DEPRECATED("Use KDF::create")
198
199inline KDF* get_kdf(std::string_view algo_spec) {
200 auto kdf = KDF::create(algo_spec);
201 if(kdf)
202 return kdf.release();
203
204 if(algo_spec == "Raw")
205 return nullptr;
206
207 throw Algorithm_Not_Found(algo_spec);
208}
209
210} // namespace Botan
211
212#endif
Definition: kdf.h:23
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:106
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:165
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:85
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:146
virtual std::string name() const =0
virtual ~KDF()=default
KDF * clone() const
Definition: kdf.h:187
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:128
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:20
#define BOTAN_DEPRECATED(msg)
Definition: compiler.h:114
FE_25519 T
Definition: ge.cpp:34
Definition: alg_id.cpp:13
KDF * get_kdf(std::string_view algo_spec)
Definition: kdf.h:199
const uint8_t * cast_char_ptr_to_uint8(const char *s)
Definition: mem_ops.h:177
Definition: bigint.h:1030