Botan 3.14.1
Crypto and TLS for C&
Botan::FPE_FE1 Class Referencefinal

#include <fpe_fe1.h>

Inheritance diagram for Botan::FPE_FE1:
Botan::SymmetricAlgorithm

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)

Warning
This is not constant time; the length of each round's intermediate value, as input to the PRF, depends on the values being encrypted

Definition at line 28 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
nthe 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.
roundsthe number of rounds to use. Must be at least 3.
compat_modeAn error in versions before 2.5.0 chose incorrect values for a and b. Set compat_mode to true to select this version.
mac_algothe PRF to use as the encryption function

Definition at line 73 of file fpe_fe1.cpp.

73 :
74 m_n(n), m_rounds(rounds) {
75 if(m_rounds < 3) {
76 throw Invalid_Argument("FPE_FE1 rounds too small");
77 }
78
80
81 m_n_bytes = m_n.serialize();
82
83 if(m_n_bytes.size() > MAX_N_BYTES) {
84 throw Invalid_Argument("N is too large for FPE encryption");
85 }
86
87 factor(m_n, m_a, m_b);
88
89 if(compat_mode) {
90 if(m_a < m_b) {
91 std::swap(m_a, m_b);
92 }
93 } else {
94 if(m_a > m_b) {
95 std::swap(m_a, m_b);
96 }
97 }
98}
static std::unique_ptr< MessageAuthenticationCode > create_or_throw(std::string_view algo_spec, std::string_view provider="")
Definition mac.cpp:142

References Botan::MessageAuthenticationCode::create_or_throw().

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

◆ ~FPE_FE1()

Botan::FPE_FE1::~FPE_FE1 ( )
overridedefault

◆ 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]

◆ 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
predicateif false, a Key_Not_Set exception is thrown

Definition at line 186 of file sym_algo.h.

186 {
187 if(!predicate) {
188 throw_key_not_set_error();
189 }
190 }

◆ clear()

void Botan::FPE_FE1::clear ( )
overridevirtual

Reset the internal state, including the key

Implements Botan::SymmetricAlgorithm.

Definition at line 104 of file fpe_fe1.cpp.

104 {
105 m_mac->clear();
106}

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
xthe ciphertext to decrypt, where 0 <= x < n
tweakmust match the value used to encrypt
tweak_lenlength of tweak

Definition at line 175 of file fpe_fe1.cpp.

175 {
176 BOTAN_ARG_CHECK(input.signum() >= 0 && input < m_n, "Invalid FPE_FE1 input");
177
178 const secure_vector<uint8_t> tweak_mac = compute_tweak_mac(tweak, tweak_len);
179
180 BigInt X = input;
181 CT::poison(X);
183
184 BigInt W;
185 BigInt R;
186 BigInt Fi;
187 for(size_t i = 0; i != m_rounds; ++i) {
188 ct_divide(X, m_a, R, W);
189
190 Fi = F(R, m_rounds - i - 1, tweak_mac, tmp);
191 X = m_b * ct_modulo(W - Fi, m_a) + R;
192 }
193
194 CT::unpoison(X);
195 return X;
196}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
constexpr void unpoison(const T *p, size_t n)
Definition ct_utils.h:67
constexpr void poison(const T *p, size_t n)
Definition ct_utils.h:56
BigInt ct_modulo(const BigInt &x, const BigInt &y)
Definition divide.cpp:262
void ct_divide(const BigInt &x, const BigInt &y, BigInt &q_out, BigInt &r_out)
Definition divide.cpp:180
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128

References BOTAN_ARG_CHECK, Botan::ct_divide(), Botan::ct_modulo(), Botan::CT::poison(), Botan::BigInt::signum(), and Botan::CT::unpoison().

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
xthe ciphertext to decrypt, where 0 <= x < n
tweakmust match the value used to encrypt
Returns
the plaintext

Definition at line 204 of file fpe_fe1.cpp.

204 {
205 uint8_t tweak8[8];
206 store_be(tweak, tweak8);
207 return decrypt(x, tweak8, sizeof(tweak8));
208}
BigInt decrypt(const BigInt &x, const uint8_t tweak[], size_t tweak_len) const
Definition fpe_fe1.cpp:175
constexpr auto store_be(ParamTs &&... params)
Definition loadstor.h:745

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
xthe plaintext to encrypt, where 0 <= x < n
tweakwill modify the ciphertext
tweak_lenlength of tweak

Definition at line 152 of file fpe_fe1.cpp.

152 {
153 BOTAN_ARG_CHECK(input.signum() >= 0 && input < m_n, "Invalid FPE_FE1 input");
154
155 const secure_vector<uint8_t> tweak_mac = compute_tweak_mac(tweak, tweak_len);
156
157 BigInt X = input;
158 CT::poison(X);
159
161
162 BigInt L;
163 BigInt R;
164 BigInt Fi;
165 for(size_t i = 0; i != m_rounds; ++i) {
166 ct_divide(X, m_b, L, R);
167 Fi = F(R, i, tweak_mac, tmp);
168 X = m_a * R + ct_modulo(L + Fi, m_a);
169 }
170
171 CT::unpoison(X);
172 return X;
173}

References BOTAN_ARG_CHECK, Botan::ct_divide(), Botan::ct_modulo(), Botan::CT::poison(), Botan::BigInt::signum(), and Botan::CT::unpoison().

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
xthe plaintext to encrypt, where 0 <= x < n
tweakwill modify the ciphertext
Returns
the ciphertext

Definition at line 198 of file fpe_fe1.cpp.

198 {
199 uint8_t tweak8[8];
200 store_be(tweak, tweak8);
201 return encrypt(x, tweak8, sizeof(tweak8));
202}
BigInt encrypt(const BigInt &x, const uint8_t tweak[], size_t tweak_len) const
Definition fpe_fe1.cpp:152

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

116 {
117 return m_mac->has_keying_material();
118}

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

112 {
113 return m_mac->key_spec();
114}

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.

130{ return key_spec().maximum_keylength(); }
size_t maximum_keylength() const
Definition sym_algo.h:58
virtual Key_Length_Specification key_spec() const =0

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.

136{ return key_spec().minimum_keylength(); }
size_t minimum_keylength() const
Definition sym_algo.h:52

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

108 {
109 return fmt("FPE_FE1({},{})", m_mac->name(), m_rounds);
110}
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References Botan::fmt().

◆ 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]

◆ 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
keythe to be set as a byte array.
lengthin bytes of key param

Definition at line 162 of file sym_algo.h.

162{ 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
keythe contiguous byte range to be set.

Definition at line 22 of file sym_algo.cpp.

22 {
23 if(!valid_keylength(key.size())) {
24 throw Invalid_Key_Length(name(), key.size());
25 }
26 key_schedule(key);
27}
bool valid_keylength(size_t length) const
Definition sym_algo.h:143
virtual std::string name() const =0

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
lengththe key length to be checked.
Returns
true if the key length is valid.

Definition at line 143 of file sym_algo.h.

143{ return key_spec().valid_keylength(length); }
bool valid_keylength(size_t length) const
Definition sym_algo.h:44

References key_spec().

Referenced by set_key().


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