Botan 3.8.1
Crypto and TLS for C&
fpe_fe1.h
Go to the documentation of this file.
1/*
2* Format Preserving Encryption (FE1 scheme)
3* (C) 2009,2018 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_FPE_FE1_H_
9#define BOTAN_FPE_FE1_H_
10
11#include <botan/bigint.h>
12#include <botan/sym_algo.h>
13#include <botan/symkey.h>
14#include <memory>
15
16namespace Botan {
17
19
20/**
21* Format Preserving Encryption using the scheme FE1 from the paper
22* "Format-Preserving Encryption" by Bellare, Rogaway, et al
23* (https://eprint.iacr.org/2009/251)
24*/
25class BOTAN_PUBLIC_API(2, 5) FPE_FE1 final : public SymmetricAlgorithm {
26 public:
27 /**
28 * @param n the modulus. All plaintext and ciphertext values must be
29 * less than this.
30 * @param rounds the number of rounds to use. Must be at least 3.
31 * @param compat_mode An error in versions before 2.5.0 chose incorrect
32 * values for a and b. Set compat_mode to true to select this version.
33 * @param mac_algo the PRF to use as the encryption function
34 */
35 FPE_FE1(const BigInt& n,
36 size_t rounds = 5,
37 bool compat_mode = false,
38 std::string_view mac_algo = "HMAC(SHA-256)");
39
40 ~FPE_FE1() override;
41
42 Key_Length_Specification key_spec() const override;
43
44 bool has_keying_material() const override;
45
46 std::string name() const override;
47
48 void clear() override;
49
50 /**
51 * Encrypt X from and onto the group Z_n using key and tweak
52 * @param x the plaintext to encrypt <= n
53 * @param tweak will modify the ciphertext
54 * @param tweak_len length of tweak
55 */
56 BigInt encrypt(const BigInt& x, const uint8_t tweak[], size_t tweak_len) const;
57
58 /**
59 * Decrypt X from and onto the group Z_n using key and tweak
60 * @param x the ciphertext to encrypt <= n
61 * @param tweak must match the value used to encrypt
62 * @param tweak_len length of tweak
63 */
64 BigInt decrypt(const BigInt& x, const uint8_t tweak[], size_t tweak_len) const;
65
66 BigInt encrypt(const BigInt& x, uint64_t tweak) const;
67
68 BigInt decrypt(const BigInt& x, uint64_t tweak) const;
69
70 private:
71 void key_schedule(std::span<const uint8_t> key) override;
72
73 BigInt F(const BigInt& R, size_t round, const secure_vector<uint8_t>& tweak, secure_vector<uint8_t>& tmp) const;
74
75 secure_vector<uint8_t> compute_tweak_mac(const uint8_t tweak[], size_t tweak_len) const;
76
77 std::unique_ptr<MessageAuthenticationCode> m_mac;
78 std::vector<uint8_t> m_n_bytes;
79 BigInt m_a;
80 BigInt m_b;
81 size_t m_rounds;
82};
83
84class OctetString;
85
86namespace FPE {
87
88/**
89* Format Preserving Encryption using the scheme FE1 from the paper
90* "Format-Preserving Encryption" by Bellare, Rogaway, et al
91* (https://eprint.iacr.org/2009/251)
92*
93* Encrypt X from and onto the group Z_n using key and tweak
94* @param n the modulus
95* @param X the plaintext as a BigInt
96* @param key a random key
97* @param tweak will modify the ciphertext (think of as an IV)
98*
99* @warning This function is hardcoded to use only 3 rounds which
100* may be insecure for some values of n. Prefer FPE_FE1 class
101*/
103 fe1_encrypt(const BigInt& n, const BigInt& X, const OctetString& key, const std::vector<uint8_t>& tweak);
104
105/**
106* Decrypt X from and onto the group Z_n using key and tweak
107* @param n the modulus
108* @param X the ciphertext as a BigInt
109* @param key is the key used for encryption
110* @param tweak the same tweak used for encryption
111*
112* @warning This function is hardcoded to use only 3 rounds which
113* may be insecure for some values of n. Prefer FPE_FE1 class
114*/
116 fe1_decrypt(const BigInt& n, const BigInt& X, const OctetString& key, const std::vector<uint8_t>& tweak);
117
118} // namespace FPE
119
120} // namespace Botan
121
122#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:19
BigInt encrypt(const BigInt &x, const uint8_t tweak[], size_t tweak_len) const
Definition fpe_fe1.cpp:147
void clear() override
Definition fpe_fe1.cpp:99
std::string name() const override
Definition fpe_fe1.cpp:103
FPE_FE1(const BigInt &n, size_t rounds=5, bool compat_mode=false, std::string_view mac_algo="HMAC(SHA-256)")
Definition fpe_fe1.cpp:71
bool has_keying_material() const override
Definition fpe_fe1.cpp:111
~FPE_FE1() override
Key_Length_Specification key_spec() const override
Definition fpe_fe1.cpp:107
BigInt decrypt(const BigInt &x, const uint8_t tweak[], size_t tweak_len) const
Definition fpe_fe1.cpp:164
BigInt fe1_decrypt(const BigInt &n, const BigInt &X, const SymmetricKey &key, const std::vector< uint8_t > &tweak)
Definition fpe_fe1.cpp:201
BigInt fe1_encrypt(const BigInt &n, const BigInt &X, const SymmetricKey &key, const std::vector< uint8_t > &tweak)
Definition fpe_fe1.cpp:195
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:65