Botan 3.0.0-alpha0
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/secmem.h>
12#include <botan/exceptn.h>
13#include <string>
14
15namespace Botan {
16
17/**
18* Key Derivation Function
19*/
21 {
22 public:
23 virtual ~KDF() = default;
24
25 /**
26 * Create an instance based on a name
27 * If provider is empty then best available is chosen.
28 * @param algo_spec algorithm name
29 * @param provider provider implementation to choose
30 * @return a null pointer if the algo/provider combination cannot be found
31 */
32 static std::unique_ptr<KDF>
33 create(const std::string& algo_spec,
34 const std::string& 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>
42 create_or_throw(const std::string& algo_spec,
43 const std::string& provider = "");
44
45 /**
46 * @return list of available providers for this algorithm, empty if not available
47 */
48 static std::vector<std::string> providers(const std::string& 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 virtual void kdf(uint8_t key[], size_t key_len,
67 const uint8_t secret[], size_t secret_len,
68 const uint8_t salt[], size_t salt_len,
69 const uint8_t label[], size_t label_len) const = 0;
70
71 /**
72 * Derive a key
73 * @param key_len the desired output length in bytes
74 * @param secret the secret input
75 * @param secret_len size of secret in bytes
76 * @param salt a diversifier
77 * @param salt_len size of salt in bytes
78 * @param label purpose for the derived keying material
79 * @param label_len size of label in bytes
80 * @return the derived key
81 */
83 const uint8_t secret[],
84 size_t secret_len,
85 const uint8_t salt[],
86 size_t salt_len,
87 const uint8_t label[] = nullptr,
88 size_t label_len = 0) const
89 {
90 secure_vector<uint8_t> key(key_len);
91 kdf(key.data(), key.size(), secret, secret_len, salt, salt_len, label, label_len);
92 return key;
93 }
94
95 /**
96 * Derive a key
97 * @param key_len the desired output length in bytes
98 * @param secret the secret input
99 * @param salt a diversifier
100 * @param label purpose for the derived keying material
101 * @return the derived key
102 */
104 const secure_vector<uint8_t>& secret,
105 const std::string& salt = "",
106 const std::string& label = "") const
107 {
108 return derive_key(key_len, secret.data(), secret.size(),
109 cast_char_ptr_to_uint8(salt.data()),
110 salt.length(),
111 cast_char_ptr_to_uint8(label.data()),
112 label.length());
113
114 }
115
116 /**
117 * Derive a key
118 * @param key_len the desired output length in bytes
119 * @param secret the secret input
120 * @param salt a diversifier
121 * @param label purpose for the derived keying material
122 * @return the derived key
123 */
124 template<typename Alloc, typename Alloc2, typename Alloc3>
126 const std::vector<uint8_t, Alloc>& secret,
127 const std::vector<uint8_t, Alloc2>& salt,
128 const std::vector<uint8_t, Alloc3>& label) const
129 {
130 return derive_key(key_len,
131 secret.data(), secret.size(),
132 salt.data(), salt.size(),
133 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 */
146 const secure_vector<uint8_t>& secret,
147 const uint8_t salt[],
148 size_t salt_len,
149 const std::string& label = "") const
150 {
151 return derive_key(key_len,
152 secret.data(), secret.size(),
153 salt, salt_len,
154 cast_char_ptr_to_uint8(label.data()),
155 label.size());
156 }
157
158 /**
159 * Derive a key
160 * @param key_len the desired output length in bytes
161 * @param secret the secret input
162 * @param secret_len size of secret in bytes
163 * @param salt a diversifier
164 * @param label purpose for the derived keying material
165 * @return the derived key
166 */
168 const uint8_t secret[],
169 size_t secret_len,
170 const std::string& salt = "",
171 const std::string& label = "") const
172 {
173 return derive_key(key_len, secret, secret_len,
174 cast_char_ptr_to_uint8(salt.data()),
175 salt.length(),
176 cast_char_ptr_to_uint8(label.data()),
177 label.length());
178 }
179
180 /**
181 * @return new object representing the same algorithm as *this
182 */
183 virtual std::unique_ptr<KDF> new_object() const = 0;
184
185 /**
186 * @return new object representing the same algorithm as *this
187 */
188 KDF* clone() const
189 {
190 return this->new_object().release();
191 }
192 };
193
194/**
195* Factory method for KDF (key derivation function)
196* @param algo_spec the name of the KDF to create
197* @return pointer to newly allocated object of that type
198*
199* Prefer KDF::create
200*/
201inline KDF* get_kdf(const std::string& algo_spec)
202 {
203 auto kdf = KDF::create(algo_spec);
204 if(kdf)
205 return kdf.release();
206
207 if(algo_spec == "Raw")
208 return nullptr;
209
210 throw Algorithm_Not_Found(algo_spec);
211 }
212
213}
214
215#endif
Definition: kdf.h:21
virtual std::unique_ptr< KDF > new_object() const =0
static std::unique_ptr< KDF > create(const std::string &algo_spec, const std::string &provider="")
Definition: kdf.cpp:69
secure_vector< uint8_t > derive_key(size_t key_len, const std::vector< uint8_t, Alloc > &secret, const std::vector< uint8_t, Alloc2 > &salt, const std::vector< uint8_t, Alloc3 > &label) const
Definition: kdf.h:125
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
secure_vector< uint8_t > derive_key(size_t key_len, const secure_vector< uint8_t > &secret, const uint8_t salt[], size_t salt_len, const std::string &label="") const
Definition: kdf.h:145
secure_vector< uint8_t > derive_key(size_t key_len, const secure_vector< uint8_t > &secret, const std::string &salt="", const std::string &label="") const
Definition: kdf.h:103
virtual std::string name() const =0
secure_vector< uint8_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:82
secure_vector< uint8_t > derive_key(size_t key_len, const uint8_t secret[], size_t secret_len, const std::string &salt="", const std::string &label="") const
Definition: kdf.h:167
virtual ~KDF()=default
KDF * clone() const
Definition: kdf.h:188
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
Definition: alg_id.cpp:13
KDF * get_kdf(const std::string &algo_spec)
Definition: kdf.h:201
std::vector< T, secure_allocator< T > > secure_vector
Definition: secmem.h:65
const uint8_t * cast_char_ptr_to_uint8(const char *s)
Definition: mem_ops.h:183
size_t salt_len
Definition: x509_obj.cpp:25