From c5c144de5b5dbb03b942178ad09a66ebf5cdcb9d Mon Sep 17 00:00:00 2001 From: lloyd Date: Sun, 1 Jul 2012 20:03:29 +0000 Subject: Rename all text files that are actually reStructuredText to .rst --- doc/fpe.rst | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 doc/fpe.rst (limited to 'doc/fpe.rst') 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 +`_ 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& 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& 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 `_ to +another number with the same format, including a correct checksum. + +.. literalinclude:: examples/fpe.cpp + -- cgit v1.2.3