It's likely that other FPE methods will be desirable once they are

standardized by NIST; the FPE currently included is just a random one
that was relatively easy to implement. Move the header to fpe_fe1.h,
and rename the function. Update the example and add some documentation
for it.

3 files changed, 68 insertions, 3 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.