Botan 3.9.0
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 */
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 FPE_FE1(const FPE_FE1& other) = delete;
71 FPE_FE1(FPE_FE1&& other) noexcept;
72 FPE_FE1& operator=(const FPE_FE1& other) = delete;
73 FPE_FE1& operator=(FPE_FE1&& other) = delete;
74
75 private:
76 void key_schedule(std::span<const uint8_t> key) override;
77
78 BigInt F(const BigInt& R, size_t round, const secure_vector<uint8_t>& tweak, secure_vector<uint8_t>& tmp) const;
79
80 secure_vector<uint8_t> compute_tweak_mac(const uint8_t tweak[], size_t tweak_len) const;
81
82 std::unique_ptr<MessageAuthenticationCode> m_mac;
83 std::vector<uint8_t> m_n_bytes;
84 BigInt m_a;
85 BigInt m_b;
86 size_t m_rounds;
87};
88
89class OctetString;
90
91namespace FPE {
92
93/**
94* Format Preserving Encryption using the scheme FE1 from the paper
95* "Format-Preserving Encryption" by Bellare, Rogaway, et al
96* (https://eprint.iacr.org/2009/251)
97*
98* Encrypt X from and onto the group Z_n using key and tweak
99* @param n the modulus
100* @param X the plaintext as a BigInt
101* @param key a random key
102* @param tweak will modify the ciphertext (think of as an IV)
103*
104* @warning This function is hardcoded to use only 3 rounds which
105* may be insecure for some values of n. Prefer FPE_FE1 class
106*/
108 fe1_encrypt(const BigInt& n, const BigInt& X, const OctetString& key, const std::vector<uint8_t>& tweak);
109
110/**
111* Decrypt X from and onto the group Z_n using key and tweak
112* @param n the modulus
113* @param X the ciphertext as a BigInt
114* @param key is the key used for encryption
115* @param tweak the same tweak used for encryption
116*
117* @warning This function is hardcoded to use only 3 rounds which
118* may be insecure for some values of n. Prefer FPE_FE1 class
119*/
121 fe1_decrypt(const BigInt& n, const BigInt& X, const OctetString& key, const std::vector<uint8_t>& tweak);
122
123} // namespace FPE
124
125} // namespace Botan
126
127#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:149
void clear() override
Definition fpe_fe1.cpp:101
FPE_FE1(FPE_FE1 &&other) noexcept
FPE_FE1 & operator=(const FPE_FE1 &other)=delete
std::string name() const override
Definition fpe_fe1.cpp:105
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:71
FPE_FE1(const FPE_FE1 &other)=delete
bool has_keying_material() const override
Definition fpe_fe1.cpp:113
FPE_FE1 & operator=(FPE_FE1 &&other)=delete
~FPE_FE1() override
Key_Length_Specification key_spec() const override
Definition fpe_fe1.cpp:109
BigInt decrypt(const BigInt &x, const uint8_t tweak[], size_t tweak_len) const
Definition fpe_fe1.cpp:168
BigInt fe1_decrypt(const BigInt &n, const BigInt &X, const SymmetricKey &key, const std::vector< uint8_t > &tweak)
Definition fpe_fe1.cpp:207
BigInt fe1_encrypt(const BigInt &n, const BigInt &X, const SymmetricKey &key, const std::vector< uint8_t > &tweak)
Definition fpe_fe1.cpp:201
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:69