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, const std::string &mac_algo="HMAC(SHA-256)")
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)
template<typename Alloc >
void	set_key (const std::vector< uint8_t, Alloc > &key)
void	set_key (const uint8_t key[], size_t length)
bool	valid_keylength (size_t length) const
	~FPE_FE1 ()

Protected Member Functions
void	verify_key_set (bool cond) 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,
		const std::string &	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 59 of file fpe_fe1.cpp.

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

                                            :
   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 = BigInt::encode(n);

   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.reset(new Modular_Reducer(m_a));
   }

~FPE_FE1()

Botan::FPE_FE1::~FPE_FE1

(

)

Definition at line 91 of file fpe_fe1.cpp.

   {
   // for ~unique_ptr
   }

Member Function Documentation

clear()

void Botan::FPE_FE1::clear ( )

overridevirtual

Reset the state.

Implements Botan::SymmetricAlgorithm.

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

References Botan::ct_divide(), and X.

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

   {
   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;
   }

decrypt() [2/2]

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

Definition at line 189 of file fpe_fe1.cpp.

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

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

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

References Botan::ct_divide(), and X.

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

   {
   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;
   }

encrypt() [2/2]

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

Definition at line 182 of file fpe_fe1.cpp.

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

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

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

   {
   return m_mac->key_spec();
   }

maximum_keylength()

size_t Botan::SymmetricAlgorithm::maximum_keylength ( ) const

inlineinherited

Returns

minimum allowed key length

Definition at line 38 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 46 of file sym_algo.h.

Referenced by botan_block_cipher_get_keyspec(), and botan_mac_get_keyspec().

         {
         return key_spec().minimum_keylength();
         }

name()

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

overridevirtual

Returns

the algorithm name

Implements Botan::SymmetricAlgorithm.

Definition at line 101 of file fpe_fe1.cpp.

References Botan::ASN1::to_string().

   {
   return "FPE_FE1(" + m_mac->name() + "," + std::to_string(m_rounds) + ")";
   }

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 65 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_cipher_set_key(), botan_mac_set_key(), 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(), and Botan::FPE::fe1_encrypt().

         {
         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 71 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  )

inherited

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 17 of file sym_algo.cpp.

References Botan::SymmetricAlgorithm::name(), and Botan::SymmetricAlgorithm::valid_keylength().

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

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

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

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

verify_key_set()

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

inlineprotectedinherited

Definition at line 89 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::CAST_256::decrypt_n(), Botan::Blowfish::decrypt_n(), Botan::MISTY1::decrypt_n(), Botan::KASUMI::decrypt_n(), Botan::SHACAL2::decrypt_n(), Botan::SEED::decrypt_n(), Botan::Camellia_128::decrypt_n(), Botan::IDEA::decrypt_n(), Botan::Noekeon::decrypt_n(), Botan::DES::decrypt_n(), Botan::XTEA::decrypt_n(), Botan::Twofish::decrypt_n(), Botan::AES_128::decrypt_n(), Botan::DESX::decrypt_n(), Botan::SM4::decrypt_n(), Botan::CAST_128::decrypt_n(), Botan::Serpent::decrypt_n(), Botan::Threefish_512::decrypt_n(), Botan::Lion::decrypt_n(), Botan::ARIA_128::decrypt_n(), Botan::Camellia_192::decrypt_n(), Botan::TripleDES::decrypt_n(), Botan::ARIA_192::decrypt_n(), Botan::Camellia_256::decrypt_n(), Botan::GOST_28147_89::decrypt_n(), Botan::AES_192::decrypt_n(), Botan::ARIA_256::decrypt_n(), Botan::AES_256::decrypt_n(), Botan::IDEA::encrypt_n(), Botan::KASUMI::encrypt_n(), Botan::AES_128::encrypt_n(), Botan::MISTY1::encrypt_n(), Botan::Noekeon::encrypt_n(), Botan::CAST_128::encrypt_n(), Botan::SEED::encrypt_n(), Botan::CAST_256::encrypt_n(), Botan::SHACAL2::encrypt_n(), Botan::SM4::encrypt_n(), Botan::DES::encrypt_n(), Botan::Blowfish::encrypt_n(), Botan::Twofish::encrypt_n(), Botan::DESX::encrypt_n(), Botan::Camellia_128::encrypt_n(), Botan::XTEA::encrypt_n(), Botan::Threefish_512::encrypt_n(), Botan::Serpent::encrypt_n(), Botan::Lion::encrypt_n(), Botan::ARIA_128::encrypt_n(), Botan::Camellia_192::encrypt_n(), Botan::TripleDES::encrypt_n(), Botan::ARIA_192::encrypt_n(), Botan::Camellia_256::encrypt_n(), Botan::GOST_28147_89::encrypt_n(), Botan::AES_192::encrypt_n(), Botan::ARIA_256::encrypt_n(), Botan::AES_256::encrypt_n(), Botan::OCB_Encryption::finish(), Botan::OCB_Decryption::finish(), Botan::GHASH::ghash_update(), Botan::CFB_Encryption::process(), Botan::CFB_Decryption::process(), Botan::Salsa20::seek(), Botan::CTR_BE::seek(), Botan::ChaCha::seek(), Botan::OCB_Mode::set_associated_data(), Botan::Salsa20::set_iv(), Botan::ChaCha::set_iv(), Botan::GHASH::update(), Botan::GHASH::update_associated_data(), and Botan::ChaCha::write_keystream().

         {
         if(cond == false)
            throw_key_not_set_error();
         }

---

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