Botan::SP800_108_Pipeline Class Reference

#include <sp800_108.h>

Inheritance diagram for Botan::SP800_108_Pipeline:

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
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 override
std::string	name () const override
std::unique_ptr< KDF >	new_object () const override
	SP800_108_Pipeline (std::unique_ptr< MessageAuthenticationCode > mac)

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)

Detailed Description

NIST SP 800-108 KDF in Double Pipeline Mode (5.3)

Definition at line 96 of file sp800_108.h.

Constructor & Destructor Documentation

SP800_108_Pipeline()

Botan::SP800_108_Pipeline::SP800_108_Pipeline ( std::unique_ptr< MessageAuthenticationCode >  mac )

inlineexplicit

Definition at line 125 of file sp800_108.h.

: m_prf(std::move(mac)) {}

Member Function Documentation

clone()

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

inlineinherited

Returns

new object representing the same algorithm as *this

Definition at line 190 of file kdf.h.

         {
         return this->new_object().release();
         }

create()

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

staticinherited

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

Parameters

algo_spec	algorithm name
provider	provider implementation to choose

Returns

a null pointer if the algo/provider combination cannot be found

Definition at line 70 of file kdf.cpp.

   {
   const SCAN_Name req(algo_spec);
 
#if defined(BOTAN_HAS_HKDF)
   if(req.algo_name() == "HKDF" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         return kdf_create_mac_or_hash<HKDF>(req.arg(0));
         }
      }
 
   if(req.algo_name() == "HKDF-Extract" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         return kdf_create_mac_or_hash<HKDF_Extract>(req.arg(0));
         }
      }
 
   if(req.algo_name() == "HKDF-Expand" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         return kdf_create_mac_or_hash<HKDF_Expand>(req.arg(0));
         }
      }
#endif
 
#if defined(BOTAN_HAS_KDF2)
   if(req.algo_name() == "KDF2" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         if(auto hash = HashFunction::create(req.arg(0)))
            return std::make_unique<KDF2>(std::move(hash));
         }
      }
#endif
 
#if defined(BOTAN_HAS_KDF1_18033)
   if(req.algo_name() == "KDF1-18033" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         if(auto hash = HashFunction::create(req.arg(0)))
            return std::make_unique<KDF1_18033>(std::move(hash));
         }
      }
#endif
 
#if defined(BOTAN_HAS_KDF1)
   if(req.algo_name() == "KDF1" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         if(auto hash = HashFunction::create(req.arg(0)))
            return std::make_unique<KDF1>(std::move(hash));
         }
      }
#endif
 
#if defined(BOTAN_HAS_TLS_V12_PRF)
   if(req.algo_name() == "TLS-12-PRF" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         return kdf_create_mac_or_hash<TLS_12_PRF>(req.arg(0));
         }
      }
#endif
 
#if defined(BOTAN_HAS_X942_PRF)
   if(req.algo_name() == "X9.42-PRF" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         return std::make_unique<X942_PRF>(req.arg(0));
         }
      }
#endif
 
#if defined(BOTAN_HAS_SP800_108)
   if(req.algo_name() == "SP800-108-Counter" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         return kdf_create_mac_or_hash<SP800_108_Counter>(req.arg(0));
         }
      }
 
   if(req.algo_name() == "SP800-108-Feedback" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         return kdf_create_mac_or_hash<SP800_108_Feedback>(req.arg(0));
         }
      }
 
   if(req.algo_name() == "SP800-108-Pipeline" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         return kdf_create_mac_or_hash<SP800_108_Pipeline>(req.arg(0));
         }
      }
#endif
 
#if defined(BOTAN_HAS_SP800_56A)
   if(req.algo_name() == "SP800-56A" && req.arg_count() == 1)
      {
      if(auto hash = HashFunction::create(req.arg(0)))
         return std::make_unique<SP800_56A_Hash>(std::move(hash));
      if(auto mac = MessageAuthenticationCode::create(req.arg(0)))
         return std::make_unique<SP800_56A_HMAC>(std::move(mac));
      }
#endif
 
#if defined(BOTAN_HAS_SP800_56C)
   if(req.algo_name() == "SP800-56C" && req.arg_count() == 1)
      {
      std::unique_ptr<KDF> exp(kdf_create_mac_or_hash<SP800_108_Feedback>(req.arg(0)));
      if(exp)
         {
         if(auto mac = MessageAuthenticationCode::create(req.arg(0)))
            return std::make_unique<SP800_56C>(std::move(mac), std::move(exp));
 
         if(auto mac = MessageAuthenticationCode::create(fmt("HMAC({})", req.arg(0))))
            return std::make_unique<SP800_56C>(std::move(mac), std::move(exp));
         }
      }
#endif
 
   BOTAN_UNUSED(req);
   BOTAN_UNUSED(provider);
 
   return nullptr;
   }

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

Referenced by Botan::KDF::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 = ""  )

staticinherited

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

   {
   if(auto kdf = KDF::create(algo, provider))
      {
      return kdf;
      }
   throw Lookup_Error("KDF", algo, provider);
   }

References Botan::KDF::create(), and Botan::KDF::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/5]

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

inlineinherited

Derive a key

Parameters

key_len	the desired output length in bytes
secret	the secret input
secret_len	size of secret in bytes
salt	a diversifier
salt_len	size of salt in bytes
label	purpose for the derived keying material
label_len	size of label in bytes

Returns

the derived key

Definition at line 86 of file kdf.h.

         {
         T key(key_len);
         kdf(key.data(), key.size(), secret, secret_len, salt, salt_len, label, label_len);
         return key;
         }

References T.

derive_key() [2/5]

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

inlineinherited

Derive a key

Parameters

key_len	the desired output length in bytes
secret	the secret input
secret_len	size of secret in bytes
salt	a diversifier
label	purpose for the derived keying material

Returns

the derived key

Definition at line 170 of file kdf.h.

         {
         return derive_key<T>(key_len, secret, secret_len,
                              cast_char_ptr_to_uint8(salt.data()),
                              salt.length(),
                              cast_char_ptr_to_uint8(label.data()),
                              label.length());
         }

References Botan::cast_char_ptr_to_uint8().

derive_key() [3/5]

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

inlineinherited

Derive a key

Parameters

key_len	the desired output length in bytes
secret	the secret input
salt	a diversifier
salt_len	size of salt in bytes
label	purpose for the derived keying material

Returns

the derived key

Definition at line 148 of file kdf.h.

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

References Botan::cast_char_ptr_to_uint8().

derive_key() [4/5]

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

inlineinherited

Derive a key

Parameters

key_len	the desired output length in bytes
secret	the secret input
salt	a diversifier
label	purpose for the derived keying material

Returns

the derived key

Definition at line 127 of file kdf.h.

         {
         return derive_key<T>(key_len,
                              secret.data(), secret.size(),
                              salt.data(), salt.size(),
                              label.data(), label.size());
         }

derive_key() [5/5]

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

inlineinherited

Derive a key

Parameters

key_len	the desired output length in bytes
secret	the secret input
salt	a diversifier
label	purpose for the derived keying material

Returns

the derived key

Definition at line 105 of file kdf.h.

         {
         return derive_key<T>(key_len, secret.data(), secret.size(),
                              cast_char_ptr_to_uint8(salt.data()),
                              salt.length(),
                              cast_char_ptr_to_uint8(label.data()),
                              label.length());
 
         }

References Botan::cast_char_ptr_to_uint8().

kdf()

void Botan::SP800_108_Pipeline::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

overridevirtual

Derive a key using the SP800-108 KDF in Double Pipeline mode.

The implementation uses the optional counter i and hard codes the length of [L]_2 and [i]_2 (the value r) to 32 bits.

Parameters

key	resulting keying material
key_len	the desired output length in bytes
secret	K_I
secret_len	size of K_I in bytes
salt	Context
salt_len	size of Context in bytes
label	Label
label_len	size of Label in bytes

Exceptions

Invalid_Argument

key_len > 2^32

Implements Botan::KDF.

Definition at line 139 of file sp800_108.cpp.

   {
   const uint32_t length = static_cast<uint32_t>(key_len * 8);
   const std::size_t prf_len =  m_prf->output_length();
   const uint8_t delim = 0;
 
   const uint64_t blocks_required = (key_len + prf_len - 1) / prf_len;
 
   if(blocks_required > 0xFFFFFFFF)
      throw Invalid_Argument("SP800_108_Feedback output size too large");
 
   uint8_t *p = key;
   uint32_t counter = 1;
   uint8_t be_len[4] = { 0 };
   secure_vector<uint8_t> ai, ki;
 
   store_be(length, be_len);
   m_prf->set_key(secret,secret_len);
 
   // A(0)
   std::copy(label,label + label_len,std::back_inserter(ai));
   ai.emplace_back(delim);
   std::copy(salt,salt + salt_len,std::back_inserter(ai));
   std::copy(be_len,be_len + 4,std::back_inserter(ai));
 
   while(p < key + key_len)
      {
      // A(i)
      m_prf->update(ai);
      m_prf->final(ai);
 
      // K(i)
      const std::size_t to_copy = std::min< std::size_t >(key + key_len - p, prf_len);
      uint8_t be_cnt[4] = { 0 };
 
      store_be(counter, be_cnt);
 
      m_prf->update(ai);
      m_prf->update(be_cnt,4);
      m_prf->update(label, label_len);
      m_prf->update(delim);
      m_prf->update(salt, salt_len);
      m_prf->update(be_len,4);
      m_prf->final(ki);
 
      copy_mem(p, ki.data(), to_copy);
      p += to_copy;
 
      ++counter;
 
      BOTAN_ASSERT(counter != 0, "No overflow");
      }
   }

References BOTAN_ASSERT, Botan::copy_mem(), and Botan::store_be().

name()

std::string Botan::SP800_108_Pipeline::name ( ) const

overridevirtual

Returns

KDF name

Implements Botan::KDF.

Definition at line 129 of file sp800_108.cpp.

   {
   return fmt("SP800-108-Pipeline({})", m_prf->name());
   }

References Botan::fmt().

new_object()

std::unique_ptr< KDF > Botan::SP800_108_Pipeline::new_object ( ) const

overridevirtual

Returns

new object representing the same algorithm as *this

Implements Botan::KDF.

Definition at line 134 of file sp800_108.cpp.

   {
   return std::make_unique<SP800_108_Pipeline>(m_prf->new_object());
   }

providers()

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

staticinherited

Returns

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

Definition at line 223 of file kdf.cpp.

   {
   return probe_providers_of<KDF>(algo_spec);
   }

---

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

• src/lib/kdf/sp800_108/sp800_108.h
• src/lib/kdf/sp800_108/sp800_108.cpp