Skip to main content

Cosmian Cloudproof FPE library

Project description

Format Preserving Encryption

This library provides Format Preserving Encryption (FPE) techniques for use in a zero-trust environment. These techniques are based on FPE-FF1 which is described in NIST:800-38G.

Format Preserving Encryption (FPE)

FPE aims to encrypt plaintext while retaining its format (alphabet). FPE-FF1 is a normalized algorithm that uses symmetric encryption, but it's not as fast or secure as standardized symmetric (or public key) encryption methods like AES or ChaCha. It should only be used where the format of the ciphertext container is constrained (e.g., a fixed database schema that cannot be changed).

Implementation

The FPE implementation follows NIST specifications for FF1 (found in the NIST SP 800-38G specification).

The code is based on the cosmian_fpe directory found on GitHub, which is based on str4d/fpe. The number of Feistel rounds has been increased to 18 following the recommendations of this cryptanalysis paper.

The implementation also enforces the requirement that radix^min_len > 1_000_000. For the Alphabet and Integer FPE facilities, this requirement is met with the following parameters:

radix example alphabet min text len
2 "01" 20
10 "01234567890" 6
16 "01234567890abcdef" 5

Using FPE

Cosmian FPE proposes 3 structures:

  • fpe::Alphabet to encrypt text
  • fpe::Integer to encrypt integers with various radixes
  • fpe::Float to encrypt floating numbers

Encrypting Text

The fpe::Alphabet structure provides the ability to encrypt a plaintext using an alphabet. Characters of the plaintext that belong to the alphabet are encrypted while the others are left unchanged at their original location in the ciphertext.

An alphabet can be instantiated using the Alphabet::instantiate() method:

let hexadecimal_alphabet = Alphabet::instantiate("01234567890abcdef").unwrap();

There are multiple pre-defined alphabets available:

  • Alphabet::alpha()
  • Alphabet::alpha_lower()
  • Alphabet::alpha_upper()
  • Alphabet::numeric()
  • Alphabet::hexa_decimal()
  • Alphabet::alpha_numeric()
  • Alphabet::chinese()
  • Alphabet::latin1sup()
  • Alphabet::latin1sup_alphanum()

These alphabets can easily be extended using the extend_with method

//0-9a-zA-Z
let mut alphabet = Alphabet::alphanumeric();
// add the space character
alphabet.extend_with(" ");
Encrypting and decrypting an alphanumeric text
let key = [0_u8; 32];
let tweak = b"unique tweak";

let alphabet = Alphabet::alpha_numeric(); //0-9a-zA-Z

let ciphertext = alphabet.encrypt(&key, tweak, "alphanumeric").unwrap();
assert_eq!("jraqSuFWZmdH", ciphertext);

let plaintext = alphabet.decrypt(&key, tweak, &ciphertext).unwrap();
assert_eq!("alphanumeric", plaintext);
Encrypting and decrypting a credit card number
let key = [0_u8; 32];
let tweak = b"unique tweak";

let alphabet = Alphabet::numeric(); //0-9

let ciphertext = alphabet
   .encrypt(&key, tweak, "1234-1234-1234-1234")
   .unwrap();
assert_eq!("1415-4650-5562-7272", ciphertext);

let plaintext = alphabet.decrypt(&key, tweak, &ciphertext).unwrap();
assert_eq!("1234-1234-1234-1234", plaintext);

Note: since the - character is not part of the alphabet it is preserved during encryption and decryption.

Encrypting and decrypting a Chinese text with spaces
let key = [0_u8; 32];
let tweak = b"unique tweak";

let mut alphabet = Alphabet::chinese();
// add the space character to the alphabet
alphabet.extend_with(" ");

let ciphertext = alphabet.encrypt(&key, tweak, "天地玄黄 宇宙洪荒").unwrap();
assert_eq!("儖濣鈍媺惐墷礿截媃", ciphertext);

let plaintext = alphabet.decrypt(&key, tweak, &ciphertext).unwrap();
assert_eq!("天地玄黄 宇宙洪荒", plaintext);

Note: since the space character was added to the alphabet, it is also encrypted.

Encrypting Integers

The fpe::Integer structure offers the ability to encrypt integers with a radix between 2 (binary) and 16 (hexadecimal) and up to a maximum power of this radix.

To encrypt decimal integers up to u64::MAX, use:

let key = [0_u8; 32];
let tweak = b"unique tweak";

// decimal number with digits 0-9
let radix = 10_u32;
// the number of digits of the biggest number = radix^digits -1
// In this case 6 decimal digits -> 999_999
let digits = 6;

let itg = Integer::instantiate(radix, digits).unwrap();

let ciphertext = itg.encrypt(&key, tweak, 123_456_u64).unwrap();
assert_eq!(110_655_u64, ciphertext);

let plaintext = itg.decrypt(&key, tweak, ciphertext).unwrap();
assert_eq!(123_456_u64, plaintext);

There is also support for Big Unsigned Integers

let key = [0_u8; 32];
let tweak = b"unique tweak";

// decimal number with digits 0-9
let radix = 10_u32;
// the number of digits of the greatest number = radix^digits -1 = 10^20-1
let digits = 20;

// the value to encrypt: 10^17
let value = BigUint::from_str_radix("100000000000000000", radix).unwrap();

let itg = Integer::instantiate(radix, digits).unwrap();

let ciphertext = itg.encrypt_big(&key, tweak, &value).unwrap();
assert_eq!(
   BigUint::from_str_radix("65348521845006160218", radix).unwrap(),
   ciphertext
);

let plaintext = itg.decrypt_big(&key, tweak, &ciphertext).unwrap();
assert_eq!(
   BigUint::from_str_radix("100000000000000000", radix).unwrap(),
   plaintext
);

Encrypting Floats

The fpe::Float structure provides support for encrypting floats of type f64:

let key = [0_u8; 32];
let tweak = b"unique tweak";

let flt = Float::instantiate().unwrap();
let ciphertext = flt.encrypt(&key, tweak, 123_456.789_f64).unwrap();
assert_eq!(1.170438892319619e91_f64, ciphertext);

let plaintext = flt.decrypt(&key, tweak, ciphertext).unwrap();
assert_eq!(123_456.789_f64, plaintext);

Tweaks

Tweaks are public parameters that should vary with each instance of the encryption whenever possible. Tweaks are described in NIST:800-38G: Appendix C. There is no size limit for the tweak.

Benchmarks

Run quick start

Run cargo criterion from the current directory (./crates/fpe).

Run detailed report (Linux, MacOS)

  1. Install criterion and criterion-table

    cargo install cargo-criterion
    cargo install criterion-table
    
  2. From the root of the project, run

    bash ./benches/benches.sh
    
  3. The benchmarks are then available in ./benches/BENCHMARKS.md

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

cloudproof_fpe-0.2.2-cp37-abi3-win_amd64.whl (283.8 kB view details)

Uploaded CPython 3.7+ Windows x86-64

cloudproof_fpe-0.2.2-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (310.2 kB view details)

Uploaded CPython 3.7+ manylinux: glibc 2.17+ x86-64

cloudproof_fpe-0.2.2-cp37-abi3-macosx_10_12_x86_64.whl (286.7 kB view details)

Uploaded CPython 3.7+ macOS 10.12+ x86-64

File details

Details for the file cloudproof_fpe-0.2.2-cp37-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for cloudproof_fpe-0.2.2-cp37-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 65aeb5dda2ecfd34845f0c52f4f845896742f7238c7560b15029f6a8018ba458
MD5 c7134f48f041ed9e8cf6ae01a7393c51
BLAKE2b-256 cb9c15b9b0cb9c6ae9852b4ec5fa6cf3836197d83b5257bea6c5512ce977bf03

See more details on using hashes here.

File details

Details for the file cloudproof_fpe-0.2.2-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for cloudproof_fpe-0.2.2-cp37-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2dfae7c2b9529758f86fd2538fc2fe1e545e6fb1afa125d0ff076f2a157f99d1
MD5 380983d4ed732ab63b2e22b78fa25897
BLAKE2b-256 c01d77ea5348eae387e742cc3205d3c2ea30de73d8283d522ca7885c3bd704cd

See more details on using hashes here.

File details

Details for the file cloudproof_fpe-0.2.2-cp37-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for cloudproof_fpe-0.2.2-cp37-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 4d148bf452a0c66610c734bfef28dd51a24aec99797692987fd5e6501ee228aa
MD5 f0d95dc08023c3f398d9ec1b4351ac97
BLAKE2b-256 dc84a175348e0b7ccdb976363f4c2d5a49f2cfc7d186726aae8dc093f37913ab

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page