ff3

What it is and what it does

FF3 is a Python implementation of the NIST FF3 and FF3-1 format-preserving encryption algorithms. It encrypts data using a Feistel cipher while keeping the output in the same format as the input—numbers stay numbers, custom alphabets stay within their alphabet. This makes it useful for encrypting sensitive data like credit card numbers or identification codes while maintaining their original structure for systems that expect a specific format.

The package depends only on pycryptodome for AES encryption and supports radix values from 2 to 256, allowing encryption of digits, alphanumeric strings, or custom character sets. It includes command-line tools (ff3_encrypt, ff3_decrypt) and passes official NIST test vectors. However, the description explicitly notes that NIST withdrew FF3 from its standard in February 2025 due to published vulnerabilities, and the package carries no warranty. It is intended for developers and researchers familiar with cryptographic standards.

Use it for:

• Encrypt credit card numbers or bank account identifiers while preserving their numeric format for legacy systems that validate digit-only strings.
• Tokenize personally identifiable information (PII) like social security numbers or driver license numbers in a reversible, format-preserving way.
• Encrypt custom identifiers (e.g., order IDs, patient records) using a custom alphabet while maintaining the original character set.
• Educational and research exploration of format-preserving encryption and Feistel cipher design.
• Reversible data obfuscation for testing or development environments where you need to mask real data but recover it later.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Implements NIST FF3 and FF3-1 format-preserving encryption (FPE) algorithms to encrypt data while preserving its format—digits remain digits, custom alphabets remain within their alphabet.

No—not for new production systems. NIST formally withdrew FF3 from its standard in February 2025 due to published vulnerabilities. The package itself carries no warranty and is explicitly labeled for educational and experimental use only. If you have an existing FF3 deployment, this implementation passes official test vectors, but for new projects requiring format-preserving encryption, you should evaluate alternatives or wait for NIST's approved successor. Use only if you fully understand the cryptographic risks and your threat model accepts them.

Install

ff3 on PyPI

pip install ff3

uv add ff3

poetry add ff3

Installing ff3

Before you install

Low friction: pure Python wheel with a single dependency (pycryptodome). Last release was 200 days ago; repository is active but maintenance is aging. Suitable for projects that can tolerate infrequent updates.

License in practice

Apache 2.0 permissive license allows commercial and private use without restriction, though you must retain license notices in distributions.

Quickstart

pip install ff3

from ff3 import FF3Cipher

key = "2DE79D232DF5585D68CE47882AE256D6"
tweak = "CBD09280979564"
c = FF3Cipher(key, tweak)
ciphertext = c.encrypt("3992520240")
decrypted = c.decrypt(ciphertext)

Requires Python 3.10 or later. Key must be 128, 192, or 256 bits; tweak must be 7 bytes (FF3-1) or 8 bytes (FF3). Plaintext length is limited by radix: radix 10 allows max 56 characters, radix 36 allows max 36 characters.

Verify before relying

• Whether this package has undergone independent security review or formal cryptographic validation beyond NIST test vectors.
• Current status and adoption of FF3-1 in production systems, given NIST's February 2025 withdrawal of FF3 from the standard.
• Real-world performance on modern hardware (benchmark in description is from MacBook Air with 1.1 GHz i5, not current).

Package facts

Evidence: ff3-1.0.3-py3-none-any.whl

Tags

More Cryptography packages