diff options
-rw-r--r-- | doc/examples/fpe.cpp | 6 | ||||
-rw-r--r-- | doc/fpe.txt | 58 | ||||
-rw-r--r-- | doc/log.txt | 7 | ||||
-rw-r--r-- | src/constructs/fpe_fe1/fpe_fe1.cpp (renamed from src/constructs/fpe/fpe.cpp) | 10 | ||||
-rw-r--r-- | src/constructs/fpe_fe1/fpe_fe1.h (renamed from src/constructs/fpe/fpe.h) | 14 | ||||
-rw-r--r-- | src/constructs/fpe_fe1/info.txt (renamed from src/constructs/fpe/info.txt) | 2 |
6 files changed, 85 insertions, 12 deletions
diff --git a/doc/examples/fpe.cpp b/doc/examples/fpe.cpp index a7a483d65..029a761e7 100644 --- a/doc/examples/fpe.cpp +++ b/doc/examples/fpe.cpp @@ -1,5 +1,5 @@ #include <botan/botan.h> -#include <botan/fpe.h> +#include <botan/fpe_fe1.h> #include <botan/sha160.h> using namespace Botan; @@ -70,7 +70,7 @@ u64bit encrypt_cc_number(u64bit cc_number, u64bit cc_ranked = cc_rank(cc_number); - BigInt c = fpe_encrypt(n, cc_ranked, key, sha1(acct_name)); + BigInt c = FPE::fe1_encrypt(n, cc_ranked, key, sha1(acct_name)); if(c.bits() > 50) throw std::runtime_error("FPE produced a number too large"); @@ -89,7 +89,7 @@ u64bit decrypt_cc_number(u64bit enc_cc, u64bit cc_ranked = cc_rank(enc_cc); - BigInt c = fpe_decrypt(n, cc_ranked, key, sha1(acct_name)); + BigInt c = FPE::fe1_decrypt(n, cc_ranked, key, sha1(acct_name)); if(c.bits() > 50) throw std::runtime_error("FPE produced a number too large"); diff --git a/doc/fpe.txt b/doc/fpe.txt new file mode 100644 index 000000000..80a24a70e --- /dev/null +++ b/doc/fpe.txt @@ -0,0 +1,58 @@ + +.. _fpe: + +Format Preserving Encryption +======================================== + +Format preserving encryption (FPE) refers to a set of techniques for +encrypting data such that the ciphertext has the same format as the +plaintext. For instance, you can use FPE to encrypt credit card +numbers with valid checksums such that the ciphertext is also an +credit card number with a valid checksum, or similiarly for bank +account numbers, US Social Security numbers, or even more general +mappings like English words onto other English words. + +The scheme currently implemented in botan is called FE1, and described +in the paper `Format Preserving Encryption +<http://eprint.iacr.org/2009/251>`_ by Mihir Bellare, Thomas +Ristenpart, Phillip Rogaway, and Till Stegers. FPE is an area of +ongoing standardization and it is likely that other schemes will be +included in the future. + +To use FE1, use these functions, from ``fpe_fe1.h``: + +.. cpp:function:: BigInt FPE::fe1_encrypt(const BigInt& n, const BigInt& X, \ + const SymmetricKey& key, const MemoryRegion<byte>& tweak) + + Encrypts the value *X* modulo the value *n* using the *key* and + *tweak* specified. Returns an integer less than *n*. The *tweak* is + a value that does not need to be secret that parameterizes the + encryption function. For instance, if you were encrypting a + database column with a single key, you could use a per-row-unique + integer index value as the tweak. + + To encrypt an arbitrary value using FE1, you need to use a ranking + method. Basically, the idea is to assign an integer to every value + you might encrypt. For instance, a 16 digit credit card number + consists of a 15 digit code plus a 1 digit checksum. So to encrypt + a credit card number, you first remove the checksum, encrypt the 15 + digit value modulo 10\ :sup:`15`, and then calculate what the + checksum is for the new (ciphertext) number. + +.. cpp:function:: BigInt FPE::fe1_decrypt(const BigInt& n, const BigInt& X, \ + const SymmetricKey& key, const MemoryRegion<byte>& tweak) + + Decrypts an FE1 ciphertext produced by :cpp:func:`fe1_encrypt`; the + *n*, *key* and *tweak* should be the same as that provided to the + encryption function. Returns the plaintext. + + Note that there is not any implicit authentication or checking of + data, so if you provide an incorrect key or tweak the result is + simply a random integer. + +This example encrypts a credit card number with a valid +`Luhn checksum <http://en.wikipedia.org/wiki/Luhn_algorithm>`_ to +another number with the same format, including a correct checksum. + +.. literalinclude:: examples/fpe.cpp + diff --git a/doc/log.txt b/doc/log.txt index b8a23079b..f60086c7c 100644 --- a/doc/log.txt +++ b/doc/log.txt @@ -12,6 +12,13 @@ Version 1.10.0, Not Yet Released * Further updates to the documentation +* The format preserving encryption method currently available was + presented in the header ``fpe.h`` and the functions ``fpe_encrypt`` + and ``fpe_decrypt``. These were renamed as it is likely that other + FPE schemes will be included in the future. The header is now + ``fpe_fe1.h``, and the functions are named ``fe1_encrypt`` and + ``fe1_decrypt``. See :ref:`fpe` for more information. + * A bug in 1.9.16 effectively disabled support for runtime CPU feature detection on x86 under GCC in that release. diff --git a/src/constructs/fpe/fpe.cpp b/src/constructs/fpe_fe1/fpe_fe1.cpp index 5491af133..91d328c17 100644 --- a/src/constructs/fpe/fpe.cpp +++ b/src/constructs/fpe_fe1/fpe_fe1.cpp @@ -8,7 +8,7 @@ * Distributed under the terms of the Botan license */ -#include <botan/fpe.h> +#include <botan/fpe_fe1.h> #include <botan/numthry.h> #include <botan/hmac.h> #include <botan/sha2_32.h> @@ -16,6 +16,8 @@ namespace Botan { +namespace FPE { + namespace { // Normally FPE is for SSNs, CC#s, etc, nothing too big @@ -133,7 +135,7 @@ BigInt FPE_Encryptor::operator()(size_t round_no, const BigInt& R) /* * Generic Z_n FPE encryption, FE1 scheme */ -BigInt fpe_encrypt(const BigInt& n, const BigInt& X0, +BigInt fe1_encrypt(const BigInt& n, const BigInt& X0, const SymmetricKey& key, const MemoryRegion<byte>& tweak) { @@ -161,7 +163,7 @@ BigInt fpe_encrypt(const BigInt& n, const BigInt& X0, /* * Generic Z_n FPE decryption, FD1 scheme */ -BigInt fpe_decrypt(const BigInt& n, const BigInt& X0, +BigInt fe1_decrypt(const BigInt& n, const BigInt& X0, const SymmetricKey& key, const MemoryRegion<byte>& tweak) { @@ -187,3 +189,5 @@ BigInt fpe_decrypt(const BigInt& n, const BigInt& X0, } } + +} diff --git a/src/constructs/fpe/fpe.h b/src/constructs/fpe_fe1/fpe_fe1.h index 7a4a7861a..da9a6bcb6 100644 --- a/src/constructs/fpe/fpe.h +++ b/src/constructs/fpe_fe1/fpe_fe1.h @@ -1,18 +1,20 @@ /* -* Format Preserving Encryption +* Format Preserving Encryption (FE1 scheme) * (C) 2009 Jack Lloyd * * Distributed under the terms of the Botan license */ -#ifndef BOTAN_FORMAT_PRESERVING_ENCRYPTION_H__ -#define BOTAN_FORMAT_PRESERVING_ENCRYPTION_H__ +#ifndef BOTAN_FPE_FE1_H__ +#define BOTAN_FPE_FE1_H__ #include <botan/bigint.h> #include <botan/symkey.h> namespace Botan { +namespace FPE { + /** * Encrypt X from and onto the group Z_n using key and tweak * @param n the modulus @@ -20,7 +22,7 @@ namespace Botan { * @param key a random key * @param tweak will modify the ciphertext (think of as an IV) */ -BigInt BOTAN_DLL fpe_encrypt(const BigInt& n, const BigInt& X, +BigInt BOTAN_DLL fe1_encrypt(const BigInt& n, const BigInt& X, const SymmetricKey& key, const MemoryRegion<byte>& tweak); @@ -31,10 +33,12 @@ BigInt BOTAN_DLL fpe_encrypt(const BigInt& n, const BigInt& X, * @param key is the key used for encryption * @param tweak the same tweak used for encryption */ -BigInt BOTAN_DLL fpe_decrypt(const BigInt& n, const BigInt& X, +BigInt BOTAN_DLL fe1_decrypt(const BigInt& n, const BigInt& X, const SymmetricKey& key, const MemoryRegion<byte>& tweak); } +} + #endif diff --git a/src/constructs/fpe/info.txt b/src/constructs/fpe_fe1/info.txt index 078eb2135..33b5a1c80 100644 --- a/src/constructs/fpe/info.txt +++ b/src/constructs/fpe_fe1/info.txt @@ -1,4 +1,4 @@ -define FORMAT_PRESERVING_ENCRYPTION +define FPE_FE1 <requires> hmac |