Botan 3.13.0
Crypto and TLS for C&
Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
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

References create(), create_or_throw(), and providers().

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(); }
Botan::KDF::new_object
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 73 of file kdf.cpp.

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

References Botan::SCAN_Name::algo_name(), Botan::SCAN_Name::arg(), Botan::SCAN_Name::arg_as_integer(), Botan::SCAN_Name::arg_count(), Botan::SCAN_Name::arg_count_between(), BOTAN_UNUSED, Botan::HashFunction::create(), Botan::MessageAuthenticationCode::create(), and Botan::fmt().

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}
Botan::KDF::create
static std::unique_ptr< KDF > create(std::string_view algo_spec, std::string_view provider="")
Definition kdf.cpp:73
Botan::KDF::kdf
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::KEM_Decryption_with_KDF::KEM_Decryption_with_KDF(), Botan::PK_Ops::KEM_Encryption_with_KDF::KEM_Encryption_with_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 }
Botan::KDF::derive_key
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(), and kdf().

◆ 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 }
Botan::KDF::perform_kdf
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()

virtual std::string Botan::KDF::name ( ) const
pure virtual

Return the name of this KDF

Returns
KDF name

Implemented in 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_56C_One_Step_Hash, Botan::SP800_56C_One_Step_HMAC, Botan::SP800_56C_One_Step_KMAC128, Botan::SP800_56C_One_Step_KMAC256, Botan::SP800_56C_Two_Step, Botan::TLS_12_PRF, and Botan::X942_PRF.

◆ new_object()

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

Create a new uninitialized object of the same type

Returns
new object representing the same algorithm as *this

Implemented in 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_56C_One_Step_Hash, Botan::SP800_56C_One_Step_HMAC, Botan::SP800_56C_One_Step_KMAC128, Botan::SP800_56C_One_Step_KMAC256, Botan::SP800_56C_Two_Step, Botan::TLS_12_PRF, and Botan::X942_PRF.

Referenced by clone().

◆ 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}
Botan::probe_providers_of
std::vector< std::string > probe_providers_of(std::string_view algo_spec, const std::vector< std::string > &possible={"base"})
Definition scan_name.h:99

References Botan::probe_providers_of().

Referenced by ~KDF().

The documentation for this class was generated from the following files:
Generated by doxygen 1.16.1