Botan::FPE_FE1 Class Reference

#include <fpe_fe1.h>

Inheritance diagram for Botan::FPE_FE1:

Public Member Functions
void	clear () override
BigInt	decrypt (const BigInt &x, const uint8_t tweak[], size_t tweak_len) const
BigInt	decrypt (const BigInt &x, uint64_t tweak) const
BigInt	encrypt (const BigInt &x, const uint8_t tweak[], size_t tweak_len) const
BigInt	encrypt (const BigInt &x, uint64_t tweak) const
BOTAN_FUTURE_EXPLICIT	FPE_FE1 (const BigInt &n, size_t rounds=5, bool compat_mode=false, std::string_view mac_algo="HMAC(SHA-256)")
	FPE_FE1 (const FPE_FE1 &other)=delete
	FPE_FE1 (FPE_FE1 &&other) noexcept
bool	has_keying_material () const override
Key_Length_Specification	key_spec () const override
size_t	maximum_keylength () const
size_t	minimum_keylength () const
std::string	name () const override
FPE_FE1 &	operator= (const FPE_FE1 &other)=delete
FPE_FE1 &	operator= (FPE_FE1 &&other)=delete
void	set_key (const OctetString &key)
void	set_key (const uint8_t key[], size_t length)
void	set_key (std::span< const uint8_t > key)
bool	valid_keylength (size_t length) const
	~FPE_FE1 () override

Protected Member Functions
void	assert_key_material_set () const
void	assert_key_material_set (bool predicate) const

Detailed Description

Format Preserving Encryption using the scheme FE1 from the paper "Format-Preserving Encryption" by Bellare, Rogaway, et al (https://eprint.iacr.org/2009/251)

Definition at line 25 of file fpe_fe1.h.

Constructor & Destructor Documentation

FPE_FE1() [1/3]

Botan::FPE_FE1::FPE_FE1	(	const BigInt &	n,
		size_t	rounds = 5,
		bool	compat_mode = false,
		std::string_view	mac_algo = "HMAC(SHA-256)" )

Parameters

n	the modulus. All plaintext and ciphertext values must be less than this.
rounds	the number of rounds to use. Must be at least 3.
compat_mode	An error in versions before 2.5.0 chose incorrect values for a and b. Set compat_mode to true to select this version.
mac_algo	the PRF to use as the encryption function

Definition at line 71 of file fpe_fe1.cpp.

                                                                                          : m_rounds(rounds) {
   if(m_rounds < 3) {
      throw Invalid_Argument("FPE_FE1 rounds too small");
   }
 
   m_mac = MessageAuthenticationCode::create_or_throw(mac_algo);
 
   m_n_bytes = n.serialize();
 
   if(m_n_bytes.size() > MAX_N_BYTES) {
      throw Invalid_Argument("N is too large for FPE encryption");
   }
 
   factor(n, m_a, m_b);
 
   if(compat_mode) {
      if(m_a < m_b) {
         std::swap(m_a, m_b);
      }
   } else {
      if(m_a > m_b) {
         std::swap(m_a, m_b);
      }
   }
}

References Botan::MessageAuthenticationCode::create_or_throw(), and Botan::BigInt::serialize().

Referenced by FPE_FE1(), FPE_FE1(), operator=(), and operator=().

~FPE_FE1()

Botan::FPE_FE1::~FPE_FE1 ( )

overridedefault

References clear(), decrypt(), encrypt(), has_keying_material(), key_spec(), and name().

FPE_FE1() [2/3]

Botan::FPE_FE1::FPE_FE1 ( const FPE_FE1 & other )

delete

References FPE_FE1().

FPE_FE1() [3/3]

Botan::FPE_FE1::FPE_FE1 ( FPE_FE1 && other )

defaultnoexcept

References FPE_FE1().

Member Function Documentation

assert_key_material_set() [1/2]

void Botan::SymmetricAlgorithm::assert_key_material_set ( ) const

inlineprotectedinherited

Definition at line 146 of file sym_algo.h.

{ assert_key_material_set(has_keying_material()); }

References assert_key_material_set(), and has_keying_material().

Referenced by assert_key_material_set(), Botan::Salsa20::cipher_bytes(), Botan::Lion::decrypt_n(), Botan::Lion::encrypt_n(), Botan::GHASH::final(), Botan::GHASH::nonce_hash(), Botan::ChaCha::seek(), Botan::CTR_BE::seek(), Botan::Salsa20::seek(), Botan::GHASH::set_associated_data(), Botan::OCB_Mode::set_associated_data_n(), Botan::Salsa20::set_iv_bytes(), Botan::GHASH::update(), and Botan::GHASH::update_associated_data().

assert_key_material_set() [2/2]

void Botan::SymmetricAlgorithm::assert_key_material_set ( bool predicate ) const

inlineprotectedinherited

Definition at line 148 of file sym_algo.h.

                                                         {
         if(!predicate) {
            throw_key_not_set_error();
         }
      }

clear()

void Botan::FPE_FE1::clear ( )

overridevirtual

Reset the internal state. This includes not just the key, but any partial message that may have been in process.

Implements Botan::SymmetricAlgorithm.

Definition at line 101 of file fpe_fe1.cpp.

                    {
   m_mac->clear();
}

Referenced by ~FPE_FE1().

decrypt() [1/2]

BigInt Botan::FPE_FE1::decrypt	(	const BigInt &	x,
		const uint8_t	tweak[],
		size_t	tweak_len ) const

Decrypt X from and onto the group Z_n using key and tweak

Parameters

x	the ciphertext to encrypt <= n
tweak	must match the value used to encrypt
tweak_len	length of tweak

Definition at line 168 of file fpe_fe1.cpp.

                                                                                          {
   const secure_vector<uint8_t> tweak_mac = compute_tweak_mac(tweak, tweak_len);
 
   BigInt X = input;
   secure_vector<uint8_t> tmp;
 
   BigInt W;
   BigInt R;
   BigInt Fi;
   for(size_t i = 0; i != m_rounds; ++i) {
      ct_divide(X, m_a, R, W);
 
      Fi = F(R, m_rounds - i - 1, tweak_mac, tmp);
      X = m_b * ct_modulo(W - Fi, m_a) + R;
   }
 
   return X;
}

References Botan::ct_divide(), and Botan::ct_modulo().

Referenced by decrypt(), Botan::FPE::fe1_decrypt(), and ~FPE_FE1().

decrypt() [2/2]

BigInt Botan::FPE_FE1::decrypt	(	const BigInt &	x,
		uint64_t	tweak ) const

Definition at line 193 of file fpe_fe1.cpp.

                                                             {
   uint8_t tweak8[8];
   store_be(tweak, tweak8);
   return decrypt(x, tweak8, sizeof(tweak8));
}

References decrypt(), and Botan::store_be().

encrypt() [1/2]

BigInt Botan::FPE_FE1::encrypt	(	const BigInt &	x,
		const uint8_t	tweak[],
		size_t	tweak_len ) const

Encrypt X from and onto the group Z_n using key and tweak

Parameters

x	the plaintext to encrypt <= n
tweak	will modify the ciphertext
tweak_len	length of tweak

Definition at line 149 of file fpe_fe1.cpp.

                                                                                          {
   const secure_vector<uint8_t> tweak_mac = compute_tweak_mac(tweak, tweak_len);
 
   BigInt X = input;
 
   secure_vector<uint8_t> tmp;
 
   BigInt L;
   BigInt R;
   BigInt Fi;
   for(size_t i = 0; i != m_rounds; ++i) {
      ct_divide(X, m_b, L, R);
      Fi = F(R, i, tweak_mac, tmp);
      X = m_a * R + ct_modulo(L + Fi, m_a);
   }
 
   return X;
}

References Botan::ct_divide(), and Botan::ct_modulo().

Referenced by encrypt(), Botan::FPE::fe1_encrypt(), and ~FPE_FE1().

encrypt() [2/2]

BigInt Botan::FPE_FE1::encrypt	(	const BigInt &	x,
		uint64_t	tweak ) const

Definition at line 187 of file fpe_fe1.cpp.

                                                             {
   uint8_t tweak8[8];
   store_be(tweak, tweak8);
   return encrypt(x, tweak8, sizeof(tweak8));
}

References encrypt(), and Botan::store_be().

has_keying_material()

bool Botan::FPE_FE1::has_keying_material ( ) const

overridevirtual

Returns

true if a key has been set on this object

Implements Botan::SymmetricAlgorithm.

Definition at line 113 of file fpe_fe1.cpp.

                                        {
   return m_mac->has_keying_material();
}

Referenced by ~FPE_FE1().

key_spec()

Key_Length_Specification Botan::FPE_FE1::key_spec ( ) const

overridevirtual

Returns

object describing limits on key size

Implements Botan::SymmetricAlgorithm.

Definition at line 109 of file fpe_fe1.cpp.

                                                 {
   return m_mac->key_spec();
}

Referenced by ~FPE_FE1().

maximum_keylength()

size_t Botan::SymmetricAlgorithm::maximum_keylength ( ) const

inlineinherited

Returns

maximum allowed key length

Definition at line 102 of file sym_algo.h.

{ return key_spec().maximum_keylength(); }

References key_spec().

minimum_keylength()

size_t Botan::SymmetricAlgorithm::minimum_keylength ( ) const

inlineinherited

Returns

minimum allowed key length

Definition at line 107 of file sym_algo.h.

{ return key_spec().minimum_keylength(); }

References key_spec().

name()

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

overridevirtual

Returns

the algorithm name

Implements Botan::SymmetricAlgorithm.

Definition at line 105 of file fpe_fe1.cpp.

                              {
   return fmt("FPE_FE1({},{})", m_mac->name(), m_rounds);
}

References Botan::fmt().

Referenced by ~FPE_FE1().

operator=() [1/2]

FPE_FE1 & Botan::FPE_FE1::operator= ( const FPE_FE1 & other )

delete

References FPE_FE1().

operator=() [2/2]

FPE_FE1 & Botan::FPE_FE1::operator= ( FPE_FE1 && other )

delete

References FPE_FE1().

set_key() [1/3]

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

inherited

Set the symmetric key of this object.

Parameters

key	the SymmetricKey to be set.

Definition at line 14 of file sym_algo.cpp.

                                                       {
   set_key(std::span{key.begin(), key.length()});
}

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

Referenced by Botan::create_aes_row_generator(), Botan::Sodium::crypto_stream_salsa20(), Botan::Sodium::crypto_stream_salsa20_xor_ic(), Botan::Sodium::crypto_stream_xsalsa20(), Botan::Sodium::crypto_stream_xsalsa20_xor_ic(), Botan::FPE::fe1_decrypt(), Botan::FPE::fe1_encrypt(), Botan::Sphincs_Hash_Functions_Sha2::PRF_msg(), Botan::Sodium::randombytes_buf_deterministic(), Botan::TLS::TLS_NULL_HMAC_AEAD_Mode::reset(), and set_key().

set_key() [2/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 133 of file sym_algo.h.

{ set_key(std::span{key, length}); }

References set_key().

Referenced by set_key().

set_key() [3/3]

void Botan::SymmetricAlgorithm::set_key ( std::span< const uint8_t > key )

inherited

Set the symmetric key of this object.

Parameters

key	the contiguous byte range to be set.

Definition at line 22 of file sym_algo.cpp.

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

References name(), and valid_keylength().

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 114 of file sym_algo.h.

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

References key_spec().

Referenced by set_key().

---

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

• src/lib/misc/fpe_fe1/fpe_fe1.h
• src/lib/misc/fpe_fe1/fpe_fe1.cpp