Ex_fpe - Format-preserving encryption for Elixir (FF1, FF3-1)

ExFPE encrypts a numerical string into another of the same length over the same alphabet.

Use cases

• credit-card numbers - encrypt them in a field or database column that only accepts credit-card -shaped values;
• sequential integers - encrypt them while preserving their domain:
  • auto-incremented IDs in SQL databases;
  • short, temporary sharing codes that look random but are the result of encrypting the outputs of a cycling counter;
  • generate a 1-to-1 map from (sequence of consecutive integers) => (collection of seemingly random integers), in the same domain, no repeated elements.

And any other similar problems.

Example

Base 10

key = :crypto.strong_rand_bytes(32)
radix = 10
ctx = ExFPE.new!(key, radix)

tweak = "dev.env"
plaintext = "34436524"
ciphertext = ExFPE.encrypt!(ctx, tweak, plaintext)
^plaintext = ExFPE.decrypt!(ctx, tweak, ciphertext)

^ The encrypted ciphertext is always of the same length, and over the same alphabet, as plaintext.

Base 16

key = :crypto.strong_rand_bytes(32)
radix = 16
ctx = ExFPE.new!(key, radix)

tweak = "prod.env"
plaintext = "ABE19F00E22333445C"
ciphertext = ExFPE.encrypt!(ctx, tweak, plaintext)
^plaintext = ExFPE.decrypt!(ctx, tweak, ciphertext)

Custom alphabet

key = :crypto.strong_rand_bytes(32)
alphabet = "abcdeぜそぞ🦄🕞🌖"
ctx = ExFPE.new!(key, alphabet)

tweak = "tweak45"
plaintext = "🕞aebe🕞ぜそ🌖"
ciphertext = ExFPE.encrypt!(ctx, tweak, plaintext)
^plaintext = ExFPE.decrypt!(ctx, tweak, ciphertext)

Capabilities

• any base/radix from 2 up to 65535;
• optimized for bases between 2 and 36 if the alphabet matches the output of Integer.to_string/2 (upcase or downcase);
• can otherwise use custom Unicode alphabets, with restrictions on accepted symbols;
• use ExFPE to store context under your supervision tree, and access the API through generated functions that don’t require you to pass context every time;
• can also operate in raw mode, encrypting and decrypting integer values directly.

Modes

By default, ExFPE uses FF1 (ExFPE.FF1), the only mode approved by NIST in SP 800-38Gr1 2pd. The other available mode is FF3-1 (ExFPE.FF3_1), which NIST no longer recommends.

I implemented the FF3-1 mode back in 2023, before the latest recommendation - which is why it’s part of this release.

Links