Botan 3.14.1
Crypto and TLS for C&
Botan::KDF Class Referenceabstract

#include <kdf.h>

Inheritance diagram for Botan::KDF:
Botan::HKDF Botan::HKDF_Expand Botan::HKDF_Extract Botan::KDF1 Botan::KDF1_18033 Botan::KDF2 Botan::SP800_108_Counter Botan::SP800_108_Feedback Botan::SP800_108_Pipeline Botan::SP800_56A_One_Step_KMAC_Abstract Botan::SP800_56C_One_Step_HMAC Botan::SP800_56C_One_Step_Hash Botan::SP800_56C_Two_Step Botan::TLS_12_PRF Botan::X942_PRF

Public Member Functions

KDF * clone () const
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
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
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
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
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
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={})
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="")
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="")
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
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
virtual std::string name () const =0
virtual std::unique_ptr< KDF > new_object () const =0
virtual ~KDF ()=default

Static Public Member Functions

static std::unique_ptr< KDF > create (std::string_view algo_spec, std::string_view provider="")
static std::unique_ptr< KDF > create_or_throw (std::string_view algo_spec, std::string_view provider="")
static std::vector< std::string > providers (std::string_view algo_spec)

Protected Member Functions

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

Detailed Description

Key Derivation Function

Definition at line 25 of file kdf.h.

Constructor & Destructor Documentation

◆ ~KDF()

virtual Botan::KDF::~KDF ( )
virtualdefault

Member Function Documentation

◆ clone()

KDF * Botan::KDF::clone ( ) const
inline

Create a new uninitialized object of the same type

Returns
new object representing the same algorithm as *this

Definition at line 246 of file kdf.h.

246{ return this->new_object().release(); }
virtual std::unique_ptr< KDF > new_object() const =0

References new_object().

◆ create()

std::unique_ptr< KDF > Botan::KDF::create ( std::string_view algo_spec,
std::string_view provider = "" )
static

Create an instance based on a name If provider is empty then best available is chosen.

Parameters
algo_specalgorithm name
providerprovider implementation to choose
Returns
a null pointer if the algo/provider combination cannot be found

Definition at line 74 of file kdf.cpp.

74 {
75 const AlgorithmSpec req(algo_spec);
76
77#if defined(BOTAN_HAS_HKDF)
78 if(auto m = req.match("HKDF({prf})")) {
79 if(provider.empty() || provider == "base") {
80 return kdf_create_mac_or_hash<HKDF>(m->str("prf"));
81 }
82 }
83
84 if(auto m = req.match("HKDF-Extract({prf})")) {
85 if(provider.empty() || provider == "base") {
86 return kdf_create_mac_or_hash<HKDF_Extract>(m->str("prf"));
87 }
88 }
89
90 if(auto m = req.match("HKDF-Expand({prf})")) {
91 if(provider.empty() || provider == "base") {
92 return kdf_create_mac_or_hash<HKDF_Expand>(m->str("prf"));
93 }
94 }
95#endif
96
97#if defined(BOTAN_HAS_KDF2)
98 if(auto m = req.match("KDF2({hash})")) {
99 if(provider.empty() || provider == "base") {
100 if(auto hash = HashFunction::create(m->str("hash"))) {
101 return std::make_unique<KDF2>(std::move(hash));
102 }
103 }
104 }
105#endif
106
107#if defined(BOTAN_HAS_KDF1_18033)
108 if(auto m = req.match("KDF1-18033({hash})")) {
109 if(provider.empty() || provider == "base") {
110 if(auto hash = HashFunction::create(m->str("hash"))) {
111 return std::make_unique<KDF1_18033>(std::move(hash));
112 }
113 }
114 }
115#endif
116
117#if defined(BOTAN_HAS_KDF1)
118 if(auto m = req.match("KDF1({hash})")) {
119 if(provider.empty() || provider == "base") {
120 if(auto hash = HashFunction::create(m->str("hash"))) {
121 return std::make_unique<KDF1>(std::move(hash));
122 }
123 }
124 }
125#endif
126
127#if defined(BOTAN_HAS_TLS_V12_PRF)
128 if(auto m = req.match("TLS-12-PRF({prf})")) {
129 if(provider.empty() || provider == "base") {
130 return kdf_create_mac_or_hash<TLS_12_PRF>(m->str("prf"));
131 }
132 }
133#endif
134
135#if defined(BOTAN_HAS_X942_PRF)
136 if(auto m = req.match("X9.42-PRF({kek:str})")) {
137 if(provider.empty() || provider == "base") {
138 return std::make_unique<X942_PRF>(m->str("kek"));
139 }
140 }
141#endif
142
143#if defined(BOTAN_HAS_SP800_108)
144 if(auto m = req.match("SP800-108-Counter({prf},{r:int=32},{L:int=32})")) {
145 if(provider.empty() || provider == "base") {
146 return kdf_create_mac_or_hash<SP800_108_Counter>(m->str("prf"), m->integer("r"), m->integer("L"));
147 }
148 }
149
150 if(auto m = req.match("SP800-108-Feedback({prf},{r:int=32},{L:int=32})")) {
151 if(provider.empty() || provider == "base") {
152 return kdf_create_mac_or_hash<SP800_108_Feedback>(m->str("prf"), m->integer("r"), m->integer("L"));
153 }
154 }
155
156 if(auto m = req.match("SP800-108-Pipeline({prf},{r:int=32},{L:int=32})")) {
157 if(provider.empty() || provider == "base") {
158 return kdf_create_mac_or_hash<SP800_108_Pipeline>(m->str("prf"), m->integer("r"), m->integer("L"));
159 }
160 }
161#endif
162
163#if defined(BOTAN_HAS_SP800_56A)
164 if(auto m = req.match("SP800-56A({fn})")) {
165 if(provider.empty() || provider == "base") {
166 const auto fn = m->str("fn");
167 if(auto hash = HashFunction::create(fn)) {
168 return std::make_unique<SP800_56C_One_Step_Hash>(std::move(hash));
169 }
170 if(fn == "KMAC-128") {
171 return std::make_unique<SP800_56C_One_Step_KMAC128>();
172 }
173 if(fn == "KMAC-256") {
174 return std::make_unique<SP800_56C_One_Step_KMAC256>();
175 }
176 if(auto mac = MessageAuthenticationCode::create(fn)) {
177 return std::make_unique<SP800_56C_One_Step_HMAC>(std::move(mac));
178 }
179 }
180 }
181#endif
182
183#if defined(BOTAN_HAS_SP800_56C)
184 if(auto m = req.match("SP800-56C({prf})")) {
185 if(provider.empty() || provider == "base") {
186 const auto prf = m->str("prf");
187 std::unique_ptr<KDF> exp(kdf_create_mac_or_hash<SP800_108_Feedback>(prf, 32, 32));
188 if(exp) {
189 if(auto mac = MessageAuthenticationCode::create(fmt("HMAC({})", prf))) {
190 return std::make_unique<SP800_56C_Two_Step>(std::move(mac), std::move(exp));
191 }
192
193 if(auto mac = MessageAuthenticationCode::create(prf)) {
194 return std::make_unique<SP800_56C_Two_Step>(std::move(mac), std::move(exp));
195 }
196 }
197 }
198 }
199#endif
200
201 BOTAN_UNUSED(req);
202 BOTAN_UNUSED(provider);
203
204 return nullptr;
205}
#define BOTAN_UNUSED
Definition assert.h:151
static std::unique_ptr< HashFunction > create(std::string_view algo_spec, std::string_view provider="")
Definition hash.cpp:112
static std::unique_ptr< MessageAuthenticationCode > create(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:51
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References BOTAN_UNUSED, Botan::HashFunction::create(), Botan::MessageAuthenticationCode::create(), Botan::fmt(), and Botan::AlgorithmSpec::match().

Referenced by create_or_throw(), and ~KDF().

◆ create_or_throw()

std::unique_ptr< KDF > Botan::KDF::create_or_throw ( std::string_view algo_spec,
std::string_view provider = "" )
static

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.

Definition at line 208 of file kdf.cpp.

208 {
209 if(auto kdf = KDF::create(algo, provider)) {
210 return kdf;
211 }
212 throw Lookup_Error("KDF", algo, provider);
213}
static std::unique_ptr< KDF > create(std::string_view algo_spec, std::string_view provider="")
Definition kdf.cpp:74
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
Definition kdf.h:69

References create(), and kdf().

Referenced by botan_kdf(), Botan::TLS::PSKImporter::derive_imported_psk(), Botan::ECIES_KA_Operation::derive_secret(), Botan::get_kdf(), Botan::PK_Ops::Key_Agreement_with_KDF::Key_Agreement_with_KDF(), Botan::TLS::Callbacks::tls12_protocol_specific_kdf(), and ~KDF().

◆ derive_key() [1/9]

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T Botan::KDF::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
inline

Derive a key

Parameters
key_lenthe desired output length in bytes
secretthe secret input
secret_lensize of secret in bytes
salta diversifier
salt_lensize of salt in bytes
labelpurpose for the derived keying material
label_lensize of label in bytes
Returns
the derived key

Definition at line 93 of file kdf.h.

99 {
100 return derive_key<T>(key_len, {secret, secret_len}, {salt, salt_len}, {label, label_len});
101 }
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:93

References derive_key().

Referenced by derive_key(), derive_key(), derive_key(), derive_key(), derive_key(), Botan::hkdf_expand_label(), kdf(), Botan::HPKE::labeled_expand(), and Botan::HPKE::labeled_extract().

◆ derive_key() [2/9]

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T Botan::KDF::derive_key ( size_t key_len,
const uint8_t secret[],
size_t secret_len,
std::string_view salt = "",
std::string_view label = "" ) const
inline

Derive a key

Parameters
key_lenthe desired output length in bytes
secretthe secret input
secret_lensize of secret in bytes
salta diversifier
labelpurpose for the derived keying material
Returns
the derived key

Definition at line 181 of file kdf.h.

185 {
186 return derive_key<T>(key_len, {secret, secret_len}, _as_span(salt), _as_span(label));
187 }

References derive_key().

◆ derive_key() [3/9]

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T Botan::KDF::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
inline

Derive a key

Parameters
key_lenthe desired output length in bytes
secretthe secret input
salta diversifier
salt_lensize of salt in bytes
labelpurpose for the derived keying material
Returns
the derived key

Definition at line 162 of file kdf.h.

166 {
167 return derive_key<T>(key_len, secret, {salt, salt_len}, _as_span(label));
168 }

References derive_key().

◆ derive_key() [4/9]

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T Botan::KDF::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
inline

Derive a key

Parameters
key_lenthe desired output length in bytes
secretthe secret input
salta diversifier
labelpurpose for the derived keying material
Returns
the derived key

Definition at line 142 of file kdf.h.

145 {
146 T key(key_len);
147 perform_kdf(key, secret, salt, label);
148 return key;
149 }
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

References perform_kdf().

◆ derive_key() [5/9]

template<concepts::resizable_byte_buffer T = secure_vector<uint8_t>>
T Botan::KDF::derive_key ( size_t key_len,
std::span< const uint8_t > secret,
std::string_view salt = "",
std::string_view label = "" ) const
inline

Derive a key

Parameters
key_lenthe desired output length in bytes
secretthe secret input
salta diversifier
labelpurpose for the derived keying material
Returns
the derived key

Definition at line 112 of file kdf.h.

115 {
116 return derive_key<T>(key_len, secret, _as_span(salt), _as_span(label));
117 }

References derive_key().

◆ derive_key() [6/9]

template<size_t key_len>
std::array< uint8_t, key_len > Botan::KDF::derive_key ( std::span< const uint8_t > secret,
std::span< const uint8_t > salt = {},
std::span< const uint8_t > label = {} )
inline

Derive a key

Template Parameters
key_lenthe desired output length in bytes
Parameters
secretthe secret input
salta diversifier
labelpurpose for the derived keying material
Returns
the derived key

Definition at line 198 of file kdf.h.

199 {},
200 std::span<const uint8_t> label = {}) {
201 std::array<uint8_t, key_len> key{};
202 perform_kdf(key, secret, salt, label);
203 return key;
204 }

◆ derive_key() [7/9]

template<size_t key_len>
std::array< uint8_t, key_len > Botan::KDF::derive_key ( std::span< const uint8_t > secret,
std::span< const uint8_t > salt = {},
std::string_view label = "" )
inline

Derive a key

Template Parameters
key_lenthe desired output length in bytes
Parameters
secretthe secret input
salta diversifier
labelpurpose for the derived keying material
Returns
the derived key

Definition at line 215 of file kdf.h.

216 {},
217 std::string_view label = "") {
218 return derive_key<key_len>(secret, salt, _as_span(label));
219 }

◆ derive_key() [8/9]

template<size_t key_len>
std::array< uint8_t, key_len > Botan::KDF::derive_key ( std::span< const uint8_t > secret,
std::string_view salt = "",
std::string_view label = "" )
inline

Derive a key

Template Parameters
key_lenthe desired output length in bytes
Parameters
secretthe secret input
salta diversifier
labelpurpose for the derived keying material
Returns
the derived key

Definition at line 230 of file kdf.h.

232 {
233 return derive_key<key_len>(secret, _as_span(salt), _as_span(label));
234 }

References derive_key().

◆ derive_key() [9/9]

void Botan::KDF::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
inline

Derive a key

Parameters
keythe output buffer for the to-be-derived key
secretthe secret input
salta diversifier
labelpurpose for the derived keying material

Definition at line 126 of file kdf.h.

129 {
130 perform_kdf(key, secret, salt, label);
131 }

References perform_kdf().

◆ kdf()

void Botan::KDF::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
inline

Derive a key

Parameters
keybuffer holding the derived key, must be of length key_len
key_lenthe desired output length in bytes
secretthe secret input
secret_lensize of secret in bytes
salta diversifier
salt_lensize of salt in bytes
labelpurpose for the derived keying material
label_lensize of label in bytes

Definition at line 69 of file kdf.h.

76 {
77 derive_key({key, key_len}, {secret, secret_len}, {salt, salt_len}, {label, label_len});
78 }

References derive_key(), and kdf().

Referenced by create_or_throw(), and kdf().

◆ name()

◆ new_object()

virtual std::unique_ptr< KDF > Botan::KDF::new_object ( ) const
pure virtual

◆ perform_kdf()

virtual void Botan::KDF::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
protectedpure virtual

Internal customization point for subclasses

The byte size of the key span is the number of bytes to be produced by the concrete key derivation function.

Parameters
keythe output buffer for the to-be-derived key
secretthe secret input
salta diversifier
labelpurpose for the derived keying material

Referenced by derive_key(), and derive_key().

◆ providers()

std::vector< std::string > Botan::KDF::providers ( std::string_view algo_spec)
static

List the providers available for a given KDF

Returns
list of available providers for this algorithm, empty if not available

Definition at line 215 of file kdf.cpp.

215 {
216 return probe_providers_of<KDF>(algo_spec);
217}
std::vector< std::string > probe_providers_of(std::string_view algo_spec, const std::vector< std::string > &possible={"base"})

References Botan::probe_providers_of().

Referenced by ~KDF().


The documentation for this class was generated from the following files: