Botan 3.14.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*
25* @warning This is not constant time; the length of each round's intermediate
26* value, as input to the PRF, depends on the values being encrypted
27*/
28class BOTAN_PUBLIC_API(2, 5) FPE_FE1 final : public SymmetricAlgorithm {
29 public:
30 /**
31 * Create an FE1 format preserving encryption object
32 * @param n the modulus. All plaintext and ciphertext values must be
33 * less than this. The value must not be prime and should be easily
34 * factored into roughly equal size values. The common case is that
35 * the modulus is a power of 10.
36 * @param rounds the number of rounds to use. Must be at least 3.
37 * @param compat_mode An error in versions before 2.5.0 chose incorrect
38 * values for a and b. Set compat_mode to true to select this version.
39 * @param mac_algo the PRF to use as the encryption function
40 */
42 size_t rounds = 5,
43 bool compat_mode = false,
44 std::string_view mac_algo = "HMAC(SHA-256)");
45
46 ~FPE_FE1() override;
47
48 /**
49 * Return the key lengths supported by this object
50 * @return the key length specification
51 */
52 Key_Length_Specification key_spec() const override;
53
54 /**
55 * Test whether a key has been set on this object
56 * @return true if a key has been set
57 */
58 bool has_keying_material() const override;
59
60 /**
61 * Return the name of this algorithm
62 * @return the algorithm name
63 */
64 std::string name() const override;
65
66 /**
67 * Reset the internal state, including the key
68 */
69 void clear() override;
70
71 /**
72 * Encrypt X from and onto the group Z_n using key and tweak
73 * @param x the plaintext to encrypt, where 0 <= x < n
74 * @param tweak will modify the ciphertext
75 * @param tweak_len length of tweak
76 */
77 BigInt encrypt(const BigInt& x, const uint8_t tweak[], size_t tweak_len) const;
78
79 /**
80 * Decrypt X from and onto the group Z_n using key and tweak
81 * @param x the ciphertext to decrypt, where 0 <= x < n
82 * @param tweak must match the value used to encrypt
83 * @param tweak_len length of tweak
84 */
85 BigInt decrypt(const BigInt& x, const uint8_t tweak[], size_t tweak_len) const;
86
87 /**
88 * Encrypt X from and onto the group Z_n using key and tweak
89 * @param x the plaintext to encrypt, where 0 <= x < n
90 * @param tweak will modify the ciphertext
91 * @return the ciphertext
92 */
93 BigInt encrypt(const BigInt& x, uint64_t tweak) const;
94
95 /**
96 * Decrypt X from and onto the group Z_n using key and tweak
97 * @param x the ciphertext to decrypt, where 0 <= x < n
98 * @param tweak must match the value used to encrypt
99 * @return the plaintext
100 */
101 BigInt decrypt(const BigInt& x, uint64_t tweak) const;
102
103 FPE_FE1(const FPE_FE1& other) = delete;
104 /**
105 * Move constructor
106 */
107 FPE_FE1(FPE_FE1&& other) noexcept;
108 FPE_FE1& operator=(const FPE_FE1& other) = delete;
109 FPE_FE1& operator=(FPE_FE1&& other) = delete;
110
111 private:
112 void key_schedule(std::span<const uint8_t> key) override;
113
114 BigInt F(const BigInt& R, size_t round, const secure_vector<uint8_t>& tweak, secure_vector<uint8_t>& tmp) const;
115
116 secure_vector<uint8_t> compute_tweak_mac(const uint8_t tweak[], size_t tweak_len) const;
117
118 std::unique_ptr<MessageAuthenticationCode> m_mac;
119 std::vector<uint8_t> m_n_bytes;
120 BigInt m_n;
121 BigInt m_a;
122 BigInt m_b;
123 size_t m_rounds;
124};
125
126class OctetString;
127
128namespace FPE {
129
130/**
131* Format Preserving Encryption using the scheme FE1 from the paper
132* "Format-Preserving Encryption" by Bellare, Rogaway, et al
133* (https://eprint.iacr.org/2009/251)
134*
135* Encrypt X from and onto the group Z_n using key and tweak
136* @param n the modulus
137* @param X the plaintext as a BigInt
138* @param key a random key
139* @param tweak will modify the ciphertext (think of as an IV)
140*
141* @warning This function is hardcoded to use only 3 rounds which
142* may be insecure for some values of n. Prefer FPE_FE1 class
143*/
145 fe1_encrypt(const BigInt& n, const BigInt& X, const OctetString& key, const std::vector<uint8_t>& tweak);
146
147/**
148* Decrypt X from and onto the group Z_n using key and tweak
149* @param n the modulus
150* @param X the ciphertext as a BigInt
151* @param key is the key used for encryption
152* @param tweak the same tweak used for encryption
153*
154* @warning This function is hardcoded to use only 3 rounds which
155* may be insecure for some values of n. Prefer FPE_FE1 class
156*/
158 fe1_decrypt(const BigInt& n, const BigInt& X, const OctetString& key, const std::vector<uint8_t>& tweak);
159
160} // namespace FPE
161
162} // namespace Botan
163
164#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_FUTURE_EXPLICIT
Definition api.h:52
BigInt encrypt(const BigInt &x, const uint8_t tweak[], size_t tweak_len) const
Definition fpe_fe1.cpp:152
void clear() override
Definition fpe_fe1.cpp:104
FPE_FE1(FPE_FE1 &&other) noexcept
FPE_FE1 & operator=(const FPE_FE1 &other)=delete
BOTAN_FUTURE_EXPLICIT 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:73
FPE_FE1(const FPE_FE1 &other)=delete
bool has_keying_material() const override
Definition fpe_fe1.cpp:116
FPE_FE1 & operator=(FPE_FE1 &&other)=delete
~FPE_FE1() override
Key_Length_Specification key_spec() const override
Definition fpe_fe1.cpp:112
BigInt decrypt(const BigInt &x, const uint8_t tweak[], size_t tweak_len) const
Definition fpe_fe1.cpp:175
const char * name
Definition ffi_tls.h:59
BigInt fe1_decrypt(const BigInt &n, const BigInt &X, const SymmetricKey &key, const std::vector< uint8_t > &tweak)
Definition fpe_fe1.cpp:218
BigInt fe1_encrypt(const BigInt &n, const BigInt &X, const SymmetricKey &key, const std::vector< uint8_t > &tweak)
Definition fpe_fe1.cpp:212
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128