aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/examples/fpe.cpp6
-rw-r--r--doc/fpe.txt58
-rw-r--r--doc/log.txt7
-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