Botan 3.7.1
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

Member Function Documentation

◆ clone()

KDF * Botan::KDF::clone ( ) const
inline
Returns
new object representing the same algorithm as *this

Definition at line 250 of file kdf.h.

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

◆ 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 71 of file kdf.cpp.

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

202 {
203 if(auto kdf = KDF::create(algo, provider)) {
204 return kdf;
205 }
206 throw Lookup_Error("KDF", algo, provider);
207}
Botan::KDF::create
static std::unique_ptr< KDF > create(std::string_view algo_spec, std::string_view provider="")
Definition kdf.cpp:71
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::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(), and Botan::TLS::Handshake_State::protocol_specific_prf().

◆ 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

Referenced by Botan::hkdf_expand_label().

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

186 {
187 return derive_key<T>(key_len,
188 {secret, secret_len},
189 {cast_char_ptr_to_uint8(salt.data()), salt.length()},
190 {cast_char_ptr_to_uint8(label.data()), label.length()});
191 }
Botan::cast_char_ptr_to_uint8
const uint8_t * cast_char_ptr_to_uint8(const char *s)
Definition mem_ops.h:274

References Botan::cast_char_ptr_to_uint8().

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

167 {
168 return derive_key<T>(key_len, secret, {salt, salt_len}, {cast_char_ptr_to_uint8(label.data()), label.size()});
169 }

References Botan::cast_char_ptr_to_uint8().

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

146 {
147 T key(key_len);
148 perform_kdf(key, secret, salt, label);
149 return key;
150 }
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
T
FE_25519 T
Definition ge.cpp:34

References T.

◆ 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,
115 secret,
116 {cast_char_ptr_to_uint8(salt.data()), salt.length()},
117 {cast_char_ptr_to_uint8(label.data()), label.length()});
118 }

References Botan::cast_char_ptr_to_uint8().

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

203 {},
204 std::span<const uint8_t> label = {}) {
205 std::array<uint8_t, key_len> key;
206 perform_kdf(key, secret, salt, label);
207 return key;
208 }

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

220 {},
221 std::string_view label = "") {
222 return derive_key<key_len>(secret, salt, {cast_char_ptr_to_uint8(label.data()), label.size()});
223 }

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

236 {
237 return derive_key<key_len>(secret,
238 {cast_char_ptr_to_uint8(salt.data()), salt.size()},
239 {cast_char_ptr_to_uint8(label.data()), label.size()});
240 }

References Botan::cast_char_ptr_to_uint8().

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

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

◆ 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 }

Referenced by create_or_throw().

◆ 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.

◆ 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

◆ 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 209 of file kdf.cpp.

209 {
210 return probe_providers_of<KDF>(algo_spec);
211}
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().

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