Botan 3.9.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
Returns
new object representing the same algorithm as *this

Definition at line 242 of file kdf.h.

242{ 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(auto hash = HashFunction::create(req.arg(0))) {
168 return std::make_unique<SP800_56C_One_Step_Hash>(std::move(hash));
169 }
170 if(req.arg(0) == "KMAC-128") {
171 return std::make_unique<SP800_56C_One_Step_KMAC128>();
172 }
173 if(req.arg(0) == "KMAC-256") {
174 return std::make_unique<SP800_56C_One_Step_KMAC256>();
175 }
176 if(auto mac = MessageAuthenticationCode::create(req.arg(0))) {
177 return std::make_unique<SP800_56C_One_Step_HMAC>(std::move(mac));
178 }
179 }
180#endif
181
182#if defined(BOTAN_HAS_SP800_56C)
183 if(req.algo_name() == "SP800-56C" && req.arg_count() == 1) {
184 std::unique_ptr<KDF> exp(kdf_create_mac_or_hash<SP800_108_Feedback>(req.arg(0), 32, 32));
185 if(exp) {
186 if(auto mac = MessageAuthenticationCode::create(req.arg(0))) {
187 return std::make_unique<SP800_56C_Two_Step>(std::move(mac), std::move(exp));
188 }
189
190 if(auto mac = MessageAuthenticationCode::create(fmt("HMAC({})", req.arg(0)))) {
191 return std::make_unique<SP800_56C_Two_Step>(std::move(mac), std::move(exp));
192 }
193 }
194 }
195#endif
196
197 BOTAN_UNUSED(req);
198 BOTAN_UNUSED(provider);
199
200 return nullptr;
201}
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:107
Botan::MessageAuthenticationCode::create
static std::unique_ptr< MessageAuthenticationCode > create(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:51
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 204 of file kdf.cpp.

204 {
205 if(auto kdf = KDF::create(algo, provider)) {
206 return kdf;
207 }
208 throw Lookup_Error("KDF", algo, provider);
209}
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:67

References create(), and kdf().

Referenced by botan_kdf(), 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::Handshake_State::protocol_specific_prf(), 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 91 of file kdf.h.

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

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 179 of file kdf.h.

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

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 160 of file kdf.h.

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

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 140 of file kdf.h.

143 {
144 T key(key_len);
145 perform_kdf(key, secret, salt, label);
146 return key;
147 }
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 110 of file kdf.h.

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

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 196 of file kdf.h.

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

◆ 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 213 of file kdf.h.

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

◆ 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 228 of file kdf.h.

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

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 124 of file kdf.h.

127 {
128 perform_kdf(key, secret, salt, label);
129 }

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 67 of file kdf.h.

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

References derive_key(), and kdf().

Referenced by create_or_throw(), and kdf().

◆ name()

virtual std::string Botan::KDF::name ( ) const
pure virtual
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
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
Returns
list of available providers for this algorithm, empty if not available

Definition at line 211 of file kdf.cpp.

211 {
212 return probe_providers_of<KDF>(algo_spec);
213}
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:105

References Botan::probe_providers_of().

Referenced by ~KDF().

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