Botan::CMAC Class Reference

#include <cmac.h>

Inheritance diagram for Botan::CMAC:

Public Member Functions
void	clear () override
MessageAuthenticationCode *	clone () const override
	CMAC (BlockCipher *cipher)
	CMAC (const CMAC &)=delete
void	final (uint8_t out[])
secure_vector< uint8_t >	final ()
template<typename Alloc >
void	final (std::vector< uint8_t, Alloc > &out)
std::vector< uint8_t >	final_stdvec ()
Key_Length_Specification	key_spec () const override
size_t	maximum_keylength () const
size_t	minimum_keylength () const
std::string	name () const override
CMAC &	operator= (const CMAC &)=delete
size_t	output_length () const override
secure_vector< uint8_t >	process (const uint8_t in[], size_t length)
secure_vector< uint8_t >	process (const secure_vector< uint8_t > &in)
secure_vector< uint8_t >	process (const std::vector< uint8_t > &in)
secure_vector< uint8_t >	process (const std::string &in)
virtual std::string	provider () const
void	set_key (const SymmetricKey &key)
template<typename Alloc >
void	set_key (const std::vector< uint8_t, Alloc > &key)
void	set_key (const uint8_t key[], size_t length)
template<typename Alloc >
void	start (const std::vector< uint8_t, Alloc > &nonce)
void	start (const uint8_t nonce[], size_t nonce_len)
void	start ()
virtual void	start_msg (const uint8_t nonce[], size_t nonce_len)
void	update (const uint8_t in[], size_t length)
void	update (const secure_vector< uint8_t > &in)
void	update (const std::vector< uint8_t > &in)
void	update (const std::string &str)
void	update (uint8_t in)
template<typename T >
void	update_be (const T in)
bool	valid_keylength (size_t length) const
virtual bool	verify_mac (const uint8_t in[], size_t length)
virtual bool	verify_mac (const std::vector< uint8_t > &in)
virtual bool	verify_mac (const secure_vector< uint8_t > &in)

Static Public Member Functions
static std::unique_ptr< MessageAuthenticationCode >	create (const std::string &algo_spec, const std::string &provider="")
static std::unique_ptr< MessageAuthenticationCode >	create_or_throw (const std::string &algo_spec, const std::string &provider="")
static secure_vector< uint8_t >	poly_double (const secure_vector< uint8_t > &in)
static std::vector< std::string >	providers (const std::string &algo_spec)

Protected Member Functions
void	verify_key_set (bool cond) const

Detailed Description

CMAC, also known as OMAC1

Definition at line 19 of file cmac.h.

Constructor & Destructor Documentation

CMAC() [1/2]

Botan::CMAC::CMAC ( BlockCipher *  cipher )

explicit

Parameters

cipher

the block cipher to use

Definition at line 120 of file cmac.cpp.

Referenced by clone().

                              :
   m_cipher(cipher),
   m_block_size(m_cipher->block_size())
   {
   if(poly_double_supported_size(m_block_size) == false)
      {
      throw Invalid_Argument("CMAC cannot use the " +
                             std::to_string(m_block_size * 8) +
                             " bit cipher " + m_cipher->name());
      }

   m_state.resize(output_length());
   m_buffer.resize(output_length());
   m_B.resize(output_length());
   m_P.resize(output_length());
   m_position = 0;
   }

CMAC() [2/2]

Botan::CMAC::CMAC ( const CMAC &  )

delete

Member Function Documentation

clear()

void Botan::CMAC::clear ( )

overridevirtual

Reset the state.

Implements Botan::SymmetricAlgorithm.

Definition at line 91 of file cmac.cpp.

References Botan::zeroise().

   {
   m_cipher->clear();
   zeroise(m_state);
   zeroise(m_buffer);
   zeroise(m_B);
   zeroise(m_P);
   m_position = 0;
   }

clone()

MessageAuthenticationCode * Botan::CMAC::clone ( ) const

overridevirtual

Get a new object representing the same algorithm as *this

Implements Botan::MessageAuthenticationCode.

Definition at line 112 of file cmac.cpp.

References CMAC().

   {
   return new CMAC(m_cipher->clone());
   }

create()

std::unique_ptr< MessageAuthenticationCode > Botan::MessageAuthenticationCode::create ( const std::string &  algo_spec, const std::string &  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 use

Returns

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

Definition at line 45 of file mac.cpp.

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

Referenced by botan_mac_init(), Botan::PBKDF::create(), Botan::KDF::create(), Botan::MessageAuthenticationCode::create_or_throw(), Botan::TLS::Session::decrypt(), Botan::TLS::Session::encrypt(), Botan::TLS::Hello_Verify_Request::Hello_Verify_Request(), Botan::hkdf_expand_label(), and Botan::RFC6979_Nonce_Generator::RFC6979_Nonce_Generator().

   {
   const SCAN_Name req(algo_spec);

#if defined(BOTAN_HAS_GMAC)
   if(req.algo_name() == "GMAC" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         if(auto bc = BlockCipher::create(req.arg(0)))
            return std::unique_ptr<MessageAuthenticationCode>(new GMAC(bc.release()));
         }
      }
#endif

#if defined(BOTAN_HAS_HMAC)
   if(req.algo_name() == "HMAC" && req.arg_count() == 1)
      {
      // TODO OpenSSL
      if(provider.empty() || provider == "base")
         {
         if(auto h = HashFunction::create(req.arg(0)))
            return std::unique_ptr<MessageAuthenticationCode>(new HMAC(h.release()));
         }
      }
#endif

#if defined(BOTAN_HAS_POLY1305)
   if(req.algo_name() == "Poly1305" && req.arg_count() == 0)
      {
      if(provider.empty() || provider == "base")
         return std::unique_ptr<MessageAuthenticationCode>(new Poly1305);
      }
#endif

#if defined(BOTAN_HAS_SIPHASH)
   if(req.algo_name() == "SipHash")
      {
      if(provider.empty() || provider == "base")
         {
         return std::unique_ptr<MessageAuthenticationCode>(
            new SipHash(req.arg_as_integer(0, 2), req.arg_as_integer(1, 4)));
         }
      }
#endif

#if defined(BOTAN_HAS_CMAC)
   if((req.algo_name() == "CMAC" || req.algo_name() == "OMAC") && req.arg_count() == 1)
      {
      // TODO: OpenSSL CMAC
      if(provider.empty() || provider == "base")
         {
         if(auto bc = BlockCipher::create(req.arg(0)))
            return std::unique_ptr<MessageAuthenticationCode>(new CMAC(bc.release()));
         }
      }
#endif


#if defined(BOTAN_HAS_CBC_MAC)
   if(req.algo_name() == "CBC-MAC" && req.arg_count() == 1)
      {
      if(provider.empty() || provider == "base")
         {
         if(auto bc = BlockCipher::create(req.arg(0)))
            return std::unique_ptr<MessageAuthenticationCode>(new CBC_MAC(bc.release()));
         }
      }
#endif

#if defined(BOTAN_HAS_ANSI_X919_MAC)
   if(req.algo_name() == "X9.19-MAC")
      {
      if(provider.empty() || provider == "base")
         {
         return std::unique_ptr<MessageAuthenticationCode>(new ANSI_X919_MAC);
         }
      }
#endif

   BOTAN_UNUSED(req);
   BOTAN_UNUSED(provider);

   return nullptr;
   }

create_or_throw()

std::unique_ptr< MessageAuthenticationCode > Botan::MessageAuthenticationCode::create_or_throw ( const std::string &  algo_spec, const std::string &  provider = ""  )

staticinherited

Definition at line 140 of file mac.cpp.

References Botan::MessageAuthenticationCode::create(), and Botan::MessageAuthenticationCode::provider().

Referenced by Botan::AutoSeeded_RNG::AutoSeeded_RNG(), Botan::ChaCha_RNG::ChaCha_RNG(), Botan::TLS::Connection_Cipher_State::Connection_Cipher_State(), Botan::ECIES_System_Params::create_mac(), Botan::CryptoBox::decrypt_bin(), Botan::CryptoBox::encrypt(), Botan::Encrypted_PSK_Database::Encrypted_PSK_Database(), Botan::FPE_FE1::FPE_FE1(), and Botan::HOTP::HOTP().

   {
   if(auto mac = MessageAuthenticationCode::create(algo, provider))
      {
      return mac;
      }
   throw Lookup_Error("MAC", algo, provider);
   }

final() [1/3]

void Botan::Buffered_Computation::final ( uint8_t  out[] )

inlineinherited

Complete the computation and retrieve the final result.

Parameters

out	The byte array to be filled with the result. Must be of length output_length()

Definition at line 89 of file buf_comp.h.

Referenced by botan_mac_final(), Botan::ed25519_gen_keypair(), Botan::ed25519_sign(), Botan::ed25519_verify(), Botan::TLS::TLS_CBC_HMAC_AEAD_Encryption::finish(), Botan::TLS::TLS_CBC_HMAC_AEAD_Decryption::finish(), and Botan::pbkdf2().

{ final_result(out); }

final() [2/3]

secure_vector<uint8_t> Botan::Buffered_Computation::final ( )

inlineinherited

Complete the computation and retrieve the final result.

Returns

secure_vector holding the result

Definition at line 96 of file buf_comp.h.

         {
         secure_vector<uint8_t> output(output_length());
         final_result(output.data());
         return output;
         }

final() [3/3]

template<typename Alloc >

void Botan::Buffered_Computation::final ( std::vector< uint8_t, Alloc > &  out )

inlineinherited

Definition at line 111 of file buf_comp.h.

         {
         out.resize(output_length());
         final_result(out.data());
         }

final_stdvec()

std::vector<uint8_t> Botan::Buffered_Computation::final_stdvec ( )

inlineinherited

Definition at line 103 of file buf_comp.h.

         {
         std::vector<uint8_t> output(output_length());
         final_result(output.data());
         return output;
         }

key_spec()

Key_Length_Specification Botan::CMAC::key_spec ( ) const

inlineoverridevirtual

Returns

object describing limits on key size

Implements Botan::SymmetricAlgorithm.

Definition at line 28 of file cmac.h.

         {
         return m_cipher->key_spec();
         }

maximum_keylength()

size_t Botan::SymmetricAlgorithm::maximum_keylength ( ) const

inlineinherited

Returns

minimum allowed key length

Definition at line 39 of file sym_algo.h.

         {
         return key_spec().maximum_keylength();
         }

minimum_keylength()

size_t Botan::SymmetricAlgorithm::minimum_keylength ( ) const

inlineinherited

Returns

maximum allowed key length

Definition at line 47 of file sym_algo.h.

         {
         return key_spec().minimum_keylength();
         }

name()

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

overridevirtual

Returns

the algorithm name

Implements Botan::SymmetricAlgorithm.

Definition at line 104 of file cmac.cpp.

   {
   return "CMAC(" + m_cipher->name() + ")";
   }

operator=()

CMAC& Botan::CMAC::operator= ( const CMAC &  )

delete

output_length()

size_t Botan::CMAC::output_length ( ) const

inlineoverridevirtual

Returns

length of the output of this function in bytes

Implements Botan::Buffered_Computation.

Definition at line 23 of file cmac.h.

{ return m_block_size; }

poly_double()

secure_vector< uint8_t > Botan::CMAC::poly_double ( const secure_vector< uint8_t > &  in )

static

CMAC's polynomial doubling operation

This function was only exposed for use elsewhere in the library, but it is not longer used. This function will be removed in a future release.

Parameters

in

the input

Definition at line 16 of file cmac.cpp.

References Botan::poly_double_n().

   {
   secure_vector<uint8_t> out(in.size());
   poly_double_n(out.data(), in.data(), out.size());
   return out;
   }

process() [1/4]

secure_vector<uint8_t> Botan::Buffered_Computation::process ( const uint8_t  in[], size_t  length  )

inlineinherited

Update and finalize computation. Does the same as calling update() and final() consecutively.

Parameters

in	the input to process as a byte array
length	the length of the byte array

Returns

the result of the call to final()

Definition at line 124 of file buf_comp.h.

         {
         add_data(in, length);
         return final();
         }

process() [2/4]

secure_vector<uint8_t> Botan::Buffered_Computation::process ( const secure_vector< uint8_t > &  in )

inlineinherited

Update and finalize computation. Does the same as calling update() and final() consecutively.

Parameters

in	the input to process

Returns

the result of the call to final()

Definition at line 136 of file buf_comp.h.

         {
         add_data(in.data(), in.size());
         return final();
         }

process() [3/4]

secure_vector<uint8_t> Botan::Buffered_Computation::process ( const std::vector< uint8_t > &  in )

inlineinherited

Update and finalize computation. Does the same as calling update() and final() consecutively.

Parameters

in	the input to process

Returns

the result of the call to final()

Definition at line 148 of file buf_comp.h.

         {
         add_data(in.data(), in.size());
         return final();
         }

process() [4/4]

secure_vector<uint8_t> Botan::Buffered_Computation::process ( const std::string &  in )

inlineinherited

Update and finalize computation. Does the same as calling update() and final() consecutively.

Parameters

in	the input to process as a string

Returns

the result of the call to final()

Definition at line 160 of file buf_comp.h.

         {
         update(in);
         return final();
         }

provider()

virtual std::string Botan::MessageAuthenticationCode::provider ( ) const

inlinevirtualinherited

Returns

provider information about this implementation. Default is "base", might also return "sse2", "avx2", "openssl", or some other arbitrary string.

Definition at line 140 of file mac.h.

Referenced by Botan::MessageAuthenticationCode::create(), and Botan::MessageAuthenticationCode::create_or_throw().

{ return "base"; }

providers()

std::vector< std::string > Botan::MessageAuthenticationCode::providers ( const std::string &  algo_spec )

staticinherited

Returns

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

Definition at line 133 of file mac.cpp.

   {
   return probe_providers_of<MessageAuthenticationCode>(algo_spec, {"base", "openssl"});
   }

set_key() [1/3]

void Botan::SymmetricAlgorithm::set_key ( const SymmetricKey &  key )

inlineinherited

Set the symmetric key of this object.

Parameters

key	the SymmetricKey to be set.

Definition at line 66 of file sym_algo.h.

References Botan::OctetString::begin(), and Botan::OctetString::length().

Referenced by Botan::aont_package(), Botan::aont_unpackage(), botan_block_cipher_set_key(), botan_mac_set_key(), Botan::FPE::fe1_decrypt(), Botan::FPE::fe1_encrypt(), and Botan::pbkdf2().

         {
         set_key(key.begin(), key.length());
         }

set_key() [2/3]

template<typename Alloc >

void Botan::SymmetricAlgorithm::set_key ( const std::vector< uint8_t, Alloc > &  key )

inlineinherited

Definition at line 72 of file sym_algo.h.

         {
         set_key(key.data(), key.size());
         }

set_key() [3/3]

void Botan::SymmetricAlgorithm::set_key ( const uint8_t  key[], size_t  length  )

inlineinherited

Set the symmetric key of this object.

Parameters

key	the to be set as a byte array.
length	in bytes of key param

Definition at line 82 of file sym_algo.h.

         {
         if(!valid_keylength(length))
            throw Invalid_Key_Length(name(), length);
         key_schedule(key, length);
         }

start() [1/3]

template<typename Alloc >

void Botan::MessageAuthenticationCode::start ( const std::vector< uint8_t, Alloc > &  nonce )

inlineinherited

Begin processing a message with a nonce

Parameters

nonce

the per message nonce

Definition at line 80 of file mac.h.

         {
         start_msg(nonce.data(), nonce.size());
         }

start() [2/3]

void Botan::MessageAuthenticationCode::start ( const uint8_t  nonce[], size_t  nonce_len  )

inlineinherited

Begin processing a message.

Parameters

nonce	the per message nonce
nonce_len	length of nonce

Definition at line 90 of file mac.h.

         {
         start_msg(nonce, nonce_len);
         }

start() [3/3]

void Botan::MessageAuthenticationCode::start ( )

inlineinherited

Begin processing a message.

Definition at line 98 of file mac.h.

         {
         return start_msg(nullptr, 0);
         }

start_msg()

virtual void Botan::MessageAuthenticationCode::start_msg ( const uint8_t  nonce[], size_t  nonce_len  )

inlinevirtualinherited

Prepare for processing a message under the specified nonce

Most MACs neither require nor support a nonce; for these algorithms calling start_msg is optional and calling it with anything other than an empty string is an error. One MAC which requires a per-message nonce be specified is GMAC.

Parameters

nonce	the message nonce bytes
nonce_len	the size of len in bytes Default implementation simply rejects all non-empty nonces since most hash/MAC algorithms do not support randomization

Definition at line 67 of file mac.h.

References BOTAN_UNUSED.

         {
         BOTAN_UNUSED(nonce);
         if(nonce_len > 0)
            throw Invalid_IV_Length(name(), nonce_len);
         }

update() [1/5]

void Botan::Buffered_Computation::update ( const uint8_t  in[], size_t  length  )

inlineinherited

Add new input to process.

Parameters

in	the input to process as a byte array
length	of param in in bytes

Definition at line 34 of file buf_comp.h.

Referenced by botan_mac_update(), Botan::ed25519_gen_keypair(), Botan::ed25519_sign(), Botan::ed25519_verify(), Botan::TLS::TLS_CBC_HMAC_AEAD_Encryption::finish(), Botan::TLS::TLS_CBC_HMAC_AEAD_Decryption::finish(), and Botan::pbkdf2().

{ add_data(in, length); }

update() [2/5]

void Botan::Buffered_Computation::update ( const secure_vector< uint8_t > &  in )

inlineinherited

Add new input to process.

Parameters

in	the input to process as a secure_vector

Definition at line 40 of file buf_comp.h.

         {
         add_data(in.data(), in.size());
         }

update() [3/5]

void Botan::Buffered_Computation::update ( const std::vector< uint8_t > &  in )

inlineinherited

Add new input to process.

Parameters

in	the input to process as a std::vector

Definition at line 49 of file buf_comp.h.

         {
         add_data(in.data(), in.size());
         }

update() [4/5]

void Botan::Buffered_Computation::update ( const std::string &  str )

inlineinherited

Add new input to process.

Parameters

str	the input to process as a std::string. Will be interpreted as a byte array based on the strings encoding.

Definition at line 72 of file buf_comp.h.

References Botan::cast_char_ptr_to_uint8().

         {
         add_data(cast_char_ptr_to_uint8(str.data()), str.size());
         }

update() [5/5]

void Botan::Buffered_Computation::update ( uint8_t  in )

inlineinherited

Process a single byte.

Parameters

in	the byte to process

Definition at line 81 of file buf_comp.h.

{ add_data(&in, 1); }

update_be()

template<typename T >

void Botan::Buffered_Computation::update_be ( const T  in )

inlineinherited

Add an integer in big-endian order

Parameters

in

the value

Definition at line 58 of file buf_comp.h.

References Botan::get_byte(), and T.

Referenced by Botan::pbkdf2().

         {
         for(size_t i = 0; i != sizeof(T); ++i)
            {
            uint8_t b = get_byte(i, in);
            add_data(&b, 1);
            }
         }

valid_keylength()

bool Botan::SymmetricAlgorithm::valid_keylength ( size_t  length ) const

inlineinherited

Check whether a given key length is valid for this algorithm.

Parameters

length

the key length to be checked.

Returns

true if the key length is valid.

Definition at line 57 of file sym_algo.h.

Referenced by Botan::aont_package(), and Botan::aont_unpackage().

         {
         return key_spec().valid_keylength(length);
         }

verify_key_set()

void Botan::SymmetricAlgorithm::verify_key_set ( bool  cond ) const

inlineprotectedinherited

Definition at line 95 of file sym_algo.h.

Referenced by Botan::Salsa20::cipher(), Botan::CTR_BE::cipher(), Botan::RC4::cipher(), Botan::SHAKE_128_Cipher::cipher(), Botan::ChaCha::cipher(), Botan::Blowfish::decrypt_n(), Botan::KASUMI::decrypt_n(), Botan::MISTY1::decrypt_n(), Botan::CAST_256::decrypt_n(), Botan::Noekeon::decrypt_n(), Botan::SHACAL2::decrypt_n(), Botan::DES::decrypt_n(), Botan::CAST_128::decrypt_n(), Botan::SM4::decrypt_n(), Botan::Camellia_128::decrypt_n(), Botan::Threefish_512::decrypt_n(), Botan::Twofish::decrypt_n(), Botan::XTEA::decrypt_n(), Botan::DESX::decrypt_n(), Botan::AES_128::decrypt_n(), Botan::IDEA::decrypt_n(), Botan::SEED::decrypt_n(), Botan::Serpent::decrypt_n(), Botan::Lion::decrypt_n(), Botan::TripleDES::decrypt_n(), Botan::Camellia_192::decrypt_n(), Botan::Camellia_256::decrypt_n(), Botan::GOST_28147_89::decrypt_n(), Botan::AES_192::decrypt_n(), Botan::AES_256::decrypt_n(), Botan::AES_128::encrypt_n(), Botan::MISTY1::encrypt_n(), Botan::CAST_256::encrypt_n(), Botan::Camellia_128::encrypt_n(), Botan::IDEA::encrypt_n(), Botan::DES::encrypt_n(), Botan::SEED::encrypt_n(), Botan::XTEA::encrypt_n(), Botan::Threefish_512::encrypt_n(), Botan::Twofish::encrypt_n(), Botan::SHACAL2::encrypt_n(), Botan::SM4::encrypt_n(), Botan::DESX::encrypt_n(), Botan::Noekeon::encrypt_n(), Botan::Blowfish::encrypt_n(), Botan::KASUMI::encrypt_n(), Botan::CAST_128::encrypt_n(), Botan::Serpent::encrypt_n(), Botan::Lion::encrypt_n(), Botan::Camellia_192::encrypt_n(), Botan::TripleDES::encrypt_n(), Botan::Camellia_256::encrypt_n(), Botan::GOST_28147_89::encrypt_n(), Botan::AES_192::encrypt_n(), Botan::AES_256::encrypt_n(), Botan::Salsa20::seek(), Botan::CTR_BE::seek(), Botan::ChaCha::seek(), and Botan::GHASH::update_associated_data().

         {
         if(cond == false)
            throw Key_Not_Set(name());
         }

verify_mac() [1/3]

bool Botan::MessageAuthenticationCode::verify_mac ( const uint8_t  in[], size_t  length  )

virtualinherited

Verify a MAC.

Parameters

in	the MAC to verify as a byte array
length	the length of param in

Returns

true if the MAC is valid, false otherwise

Definition at line 153 of file mac.cpp.

References Botan::constant_time_compare().

   {
   secure_vector<uint8_t> our_mac = final();

   if(our_mac.size() != length)
      return false;

   return constant_time_compare(our_mac.data(), mac, length);
   }

verify_mac() [2/3]

virtual bool Botan::MessageAuthenticationCode::verify_mac ( const std::vector< uint8_t > &  in )

inlinevirtualinherited

Verify a MAC.

Parameters

in	the MAC to verify as a byte array

Returns

true if the MAC is valid, false otherwise

Definition at line 116 of file mac.h.

         {
         return verify_mac(in.data(), in.size());
         }

verify_mac() [3/3]

virtual bool Botan::MessageAuthenticationCode::verify_mac ( const secure_vector< uint8_t > &  in )

inlinevirtualinherited

Verify a MAC.

Parameters

in	the MAC to verify as a byte array

Returns

true if the MAC is valid, false otherwise

Definition at line 126 of file mac.h.

         {
         return verify_mac(in.data(), in.size());
         }

---

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

• src/lib/mac/cmac/cmac.h
• src/lib/mac/cmac/cmac.cpp