ff3

library1.0.3pypypi✓ verified 86d ago

The `ff3` library provides Format Preserving Encryption (FPE) using the NIST FF3 and FF3-1 algorithms. It is currently at version 1.0.3 and receives minor updates for features and compatibility, with the core encryption logic stable since v1.0.0.

auth-security

pip install ff3

github ↗package ↗

INSTALL

IMPORT

SIG · FF3

ff3

auth-securitypythonv1.0.3

Install

2.1s avg

Import

71ms

Disk

25MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.069s · 26.4MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.1s · import 0.073s · 27MB

25MB installed

● package 25MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FF3Cipher

✓ from ff3 import FF3Cipher

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

Debug

Known issues

breakingFF3 (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.

affects: All versions since v1.0.0

gotchaThe `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.

affects: All versions since v1.0.0

gotchaWhen 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.

affects: All versions since v1.0.0

Errors

Common errors & fixes

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

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)

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'

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

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.

Upgrade

Version history

1.0.3latest on PyPI · released Jan 26, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mysto/python-fpe ↗

packagehttps://pypi.org/project/ff3/ ↗