mirror of
https://github.com/moparisthebest/mailiverse
synced 2024-11-19 07:25:05 -05:00
59 lines
2.6 KiB
Plaintext
59 lines
2.6 KiB
Plaintext
|
|
||
|
|
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 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
|
||
|
|
|