Botan 3.8.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

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

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

203 {
204 if(auto kdf = KDF::create(algo, provider)) {
205 return kdf;
206 }
207 throw Lookup_Error("KDF", algo, provider);
208}
Botan::KDF::create
static std::unique_ptr< KDF > create(std::string_view algo_spec, std::string_view provider="")
Definition kdf.cpp:72
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 210 of file kdf.cpp.

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