aboutsummaryrefslogtreecommitdiffstats
path: root/doc/fpe.rst
diff options
context:
space:
mode:
authorlloyd <[email protected]>2012-07-01 20:03:29 +0000
committerlloyd <[email protected]>2012-07-01 20:03:29 +0000
commitc5c144de5b5dbb03b942178ad09a66ebf5cdcb9d (patch)
treea1c5c8ea850206eedd428ba52c273efeae48e989 /doc/fpe.rst
parentf5f2c6d68bd31f72c5837ebc75d5a35741c3b664 (diff)
Rename all text files that are actually reStructuredText to .rst
Diffstat (limited to 'doc/fpe.rst')
-rw-r--r--doc/fpe.rst58
1 files changed, 58 insertions, 0 deletions
diff --git a/doc/fpe.rst b/doc/fpe.rst
new file mode 100644
index 000000000..776189d4f
--- /dev/null
+++ b/doc/fpe.rst
@@ -0,0 +1,58 @@
+
+Format Preserving Encryption
+========================================
+
+.. versionadded:: 1.9.17
+
+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 std::vector<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 std::vector<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
+