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
	FPE_FE1 (const BigInt &n, size_t rounds=5, bool compat_mode=false, std::string_view mac_algo="HMAC(SHA-256)")
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
void	set_key (const SymmetricKey &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 24 of file fpe_fe1.h.

Constructor & Destructor Documentation

FPE_FE1()

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 61 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);
      }
   }
 
   mod_a = std::make_unique<Modular_Reducer>(m_a);
}

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

~FPE_FE1()

Botan::FPE_FE1::~FPE_FE1 ( )

overridedefault

Member Function Documentation

assert_key_material_set() [1/2]

void Botan::SymmetricAlgorithm::assert_key_material_set ( ) const

inlineprotectedinherited

Definition at line 139 of file sym_algo.h.

{ assert_key_material_set(has_keying_material()); }

References Botan::SymmetricAlgorithm::assert_key_material_set().

Referenced by Botan::SymmetricAlgorithm::assert_key_material_set(), Botan::Salsa20::cipher_bytes(), Botan::AES_128::decrypt_n(), Botan::AES_192::decrypt_n(), Botan::AES_256::decrypt_n(), Botan::ARIA_128::decrypt_n(), Botan::ARIA_192::decrypt_n(), Botan::ARIA_256::decrypt_n(), Botan::Blowfish::decrypt_n(), Botan::Camellia_128::decrypt_n(), Botan::Camellia_192::decrypt_n(), Botan::Camellia_256::decrypt_n(), Botan::CAST_128::decrypt_n(), Botan::DES::decrypt_n(), Botan::GOST_28147_89::decrypt_n(), Botan::IDEA::decrypt_n(), Botan::Kuznyechik::decrypt_n(), Botan::Lion::decrypt_n(), Botan::Noekeon::decrypt_n(), Botan::SEED::decrypt_n(), Botan::Serpent::decrypt_n(), Botan::SHACAL2::decrypt_n(), Botan::SM4::decrypt_n(), Botan::Threefish_512::decrypt_n(), Botan::TripleDES::decrypt_n(), Botan::Twofish::decrypt_n(), Botan::AES_128::encrypt_n(), Botan::AES_192::encrypt_n(), Botan::AES_256::encrypt_n(), Botan::ARIA_128::encrypt_n(), Botan::ARIA_192::encrypt_n(), Botan::ARIA_256::encrypt_n(), Botan::Blowfish::encrypt_n(), Botan::Camellia_128::encrypt_n(), Botan::Camellia_192::encrypt_n(), Botan::Camellia_256::encrypt_n(), Botan::CAST_128::encrypt_n(), Botan::DES::encrypt_n(), Botan::GOST_28147_89::encrypt_n(), Botan::IDEA::encrypt_n(), Botan::Kuznyechik::encrypt_n(), Botan::Lion::encrypt_n(), Botan::Noekeon::encrypt_n(), Botan::SEED::encrypt_n(), Botan::Serpent::encrypt_n(), Botan::SHACAL2::encrypt_n(), Botan::SM4::encrypt_n(), Botan::Threefish_512::encrypt_n(), Botan::TripleDES::encrypt_n(), Botan::Twofish::encrypt_n(), Botan::GHASH::final(), Botan::GHASH::ghash_update(), Botan::ChaCha::seek(), Botan::CTR_BE::seek(), Botan::Salsa20::seek(), 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 141 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 91 of file fpe_fe1.cpp.

                    {
   m_mac->clear();
}

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 156 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, R, 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 * mod_a->reduce(W - Fi) + R;
   }
 
   return X;
}

References Botan::ct_divide(), and X.

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

decrypt() [2/2]

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

Definition at line 179 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 139 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, R, 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 + mod_a->reduce(L + Fi);
   }
 
   return X;
}

References Botan::ct_divide(), and X.

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

encrypt() [2/2]

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

Definition at line 173 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 103 of file fpe_fe1.cpp.

                                        {
   return m_mac->has_keying_material();
}

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 99 of file fpe_fe1.cpp.

                                                 {
   return m_mac->key_spec();
}

maximum_keylength()

size_t Botan::SymmetricAlgorithm::maximum_keylength ( ) const

inlineinherited

Returns

maximum allowed key length

Definition at line 95 of file sym_algo.h.

{ return key_spec().maximum_keylength(); }

minimum_keylength()

size_t Botan::SymmetricAlgorithm::minimum_keylength ( ) const

inlineinherited

Returns

minimum allowed key length

Definition at line 100 of file sym_algo.h.

{ return key_spec().minimum_keylength(); }

name()

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

overridevirtual

Returns

the algorithm name

Implements Botan::SymmetricAlgorithm.

Definition at line 95 of file fpe_fe1.cpp.

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

References Botan::fmt().

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

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

References Botan::OctetString::begin(), Botan::OctetString::length(), and Botan::SymmetricAlgorithm::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(), and Botan::SymmetricAlgorithm::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 126 of file sym_algo.h.

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

References Botan::SymmetricAlgorithm::set_key().

Referenced by Botan::SymmetricAlgorithm::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 17 of file sym_algo.cpp.

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

References Botan::SymmetricAlgorithm::name(), and Botan::SymmetricAlgorithm::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 107 of file sym_algo.h.

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

Referenced by Botan::SymmetricAlgorithm::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