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)" )

Create an FE1 format preserving encryption object

Parameters

n	the modulus. All plaintext and ciphertext values must be less than this. The value must not be prime and should be easily factored into roughly equal size values. The common case is that the modulus is a power of 10.
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 72 of file fpe_fe1.cpp.

                                                                                          :
      m_n(n), 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 = m_n.serialize();
 
   if(m_n_bytes.size() > MAX_N_BYTES) {
      throw Invalid_Argument("N is too large for FPE encryption");
   }
 
   factor(m_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().

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

Move constructor

References FPE_FE1().

Member Function Documentation

assert_key_material_set() [1/2]

void Botan::SymmetricAlgorithm::assert_key_material_set ( ) const

inlineprotectedinherited

Throw Key_Not_Set unless a key has been set on this object

Definition at line 180 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::Polyval::final(), Botan::Salsa20::generate_keystream(), Botan::GHASH::nonce_hash(), Botan::GHASH::reset_associated_data(), 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(), Botan::Polyval::update(), Botan::GHASH::update_associated_data(), and Botan::Polyval::zero_pad().

assert_key_material_set() [2/2]

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

inlineprotectedinherited

Throw Key_Not_Set unless the predicate holds

Parameters

predicate

if false, a Key_Not_Set exception is thrown

Definition at line 186 of file sym_algo.h.

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

clear()

void Botan::FPE_FE1::clear ( )

overridevirtual

Reset the internal state, including the key

Implements Botan::SymmetricAlgorithm.

Definition at line 103 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 decrypt, where 0 <= x < n
tweak	must match the value used to encrypt
tweak_len	length of tweak

Definition at line 172 of file fpe_fe1.cpp.

                                                                                          {
   BOTAN_ARG_CHECK(input.signum() >= 0 && input < m_n, "Invalid FPE_FE1 input");
 
   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_ARG_CHECK, Botan::ct_divide(), Botan::ct_modulo(), and Botan::BigInt::signum().

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

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

Parameters

x	the ciphertext to decrypt, where 0 <= x < n
tweak	must match the value used to encrypt

Returns

the plaintext

Definition at line 199 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, where 0 <= x < n
tweak	will modify the ciphertext
tweak_len	length of tweak

Definition at line 151 of file fpe_fe1.cpp.

                                                                                          {
   BOTAN_ARG_CHECK(input.signum() >= 0 && input < m_n, "Invalid FPE_FE1 input");
 
   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_ARG_CHECK, Botan::ct_divide(), Botan::ct_modulo(), and Botan::BigInt::signum().

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

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

Parameters

x	the plaintext to encrypt, where 0 <= x < n
tweak	will modify the ciphertext

Returns

the ciphertext

Definition at line 193 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

Test whether a key has been set on this object

Returns

true if a key has been set

Implements Botan::SymmetricAlgorithm.

Definition at line 115 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

Return the key lengths supported by this object

Returns

the key length specification

Implements Botan::SymmetricAlgorithm.

Definition at line 111 of file fpe_fe1.cpp.

                                                 {
   return m_mac->key_spec();
}

Referenced by ~FPE_FE1().

maximum_keylength()

size_t Botan::SymmetricAlgorithm::maximum_keylength ( ) const

inlineinherited

Return the largest acceptable key length

Returns

maximum allowed key length

Definition at line 130 of file sym_algo.h.

{ return key_spec().maximum_keylength(); }

References key_spec().

minimum_keylength()

size_t Botan::SymmetricAlgorithm::minimum_keylength ( ) const

inlineinherited

Return the smallest acceptable key length

Returns

minimum allowed key length

Definition at line 136 of file sym_algo.h.

{ return key_spec().minimum_keylength(); }

References key_spec().

name()

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

overridevirtual

Return the name of this algorithm

Returns

the algorithm name

Implements Botan::SymmetricAlgorithm.

Definition at line 107 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 162 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 143 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