Format Preserving Encryption (FPE) with FF3

Common errors

• ValueError: Key length must be 16, 24, or 32 bytes

  cause The provided encryption key does not meet the AES key length requirements (128, 192, or 256 bits).
  fix Ensure the `key` byte string is exactly 16, 24, or 32 bytes long. Use `.encode('utf-8')` and slice/pad if starting from a string.

• ValueError: Tweak length must be 7 bytes (FF3-1) or 8 bytes (FF3)

  cause The provided `tweak` byte string is not the correct length for the FF3 algorithm variant being used.
  fix Ensure `tweak` is 8 bytes for standard FF3 (default `FF3Cipher` constructor) or 7 bytes for FF3-1 (if using `FF3Cipher.withFF3_1`). Use `.encode('utf-8')` and slice/pad if starting from a string.

• ImportError: cannot import name 'FF3Cipher' from 'ff3'

  cause The `ff3` package is either not installed or the import path is incorrect.
  fix First, ensure installation with `pip install ff3`. If installed, verify the import statement is exactly `from ff3 import FF3Cipher`.

• TypeError: argument 'text' must be str, not bytes

  cause The `encrypt` or `decrypt` method received a bytes object when it expects a string plaintext/ciphertext.
  fix Ensure `plaintext` and `ciphertext` passed to `encrypt`/`decrypt` are `str` type. Note that `key` and `tweak` *must* be `bytes` type.

Warnings

• breaking FF3 (64-bit tweak) and FF3-1 (56-bit tweak) have different tweak length requirements. Using a tweak of incorrect length for the chosen algorithm variant will lead to `ValueError` or incorrect encryption/decryption.
  Fix: Ensure your tweak data matches the expected length for FF3 (8 bytes) or FF3-1 (7 bytes). The default `FF3Cipher` constructor uses FF3; use `FF3Cipher.withFF3_1(key, tweak)` for FF3-1.
• gotcha The `key` must be 16, 24, or 32 bytes (128, 192, or 256 bits) and the `tweak` must be 7 or 8 bytes. Providing incorrect lengths will result in a `ValueError`.
  Fix: Verify key and tweak byte lengths before instantiation. For string literals, ensure they are encoded to bytes (e.g., `'your_key_string'.encode('utf-8')`) and then sliced or padded to the exact required length.
• gotcha When using a custom alphabet via `FF3Cipher.withCustomAlphabet(key, tweak, custom_alphabet)`, the exact same alphabet must be used for both encryption and decryption, or decryption will fail.
  Fix: Persist and reuse the `FF3Cipher` instance or reconstruct it with the identical custom alphabet for decryption operations.

Install

• pip install ff3 Install stable version

Imports

• FF3Cipher

  from ff3 import FF3Cipher

Quickstart

Encrypt and decrypt a numeric string using the default FF3 algorithm with a specified key and tweak.

from ff3 import FF3Cipher
import os

# Key must be 16, 24, or 32 bytes (128, 192, or 256 bits)
# Example uses a 32-byte key
key = os.environ.get('FF3_KEY', '0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF').encode('utf-8')[:32]

# Tweak must be 7 bytes for FF3-1, 8 bytes for FF3 (default)
# Example uses an 8-byte tweak for standard FF3
tweak = os.environ.get('FF3_TWEAK', '1234567890ABCDEF').encode('utf-8')[:8]

# Initialize FF3 cipher with key and tweak
cipher = FF3Cipher(key, tweak)

# The default alphabet includes digits 0-9
plaintext = "1234567890"

ciphertext = cipher.encrypt(plaintext)
decrypted_text = cipher.decrypt(ciphertext)

print(f"Original: {plaintext}")
print(f"Encrypted: {ciphertext}")
print(f"Decrypted: {decrypted_text}")

assert plaintext == decrypted_text