README

Overview

FF3Cipher is a PHP implementation of the FPE (Format-Preserving Encryption) algorithm.

Unlike other PHP implementations, this library is capable of working with multibyte character dictionaries.

With the growth of data protection needs and the wide adoption of PHP in web applications, this project aims to bridge the gap, allowing developers to utilize FF3 encryption easily within their PHP applications.

Installation

The recommended way to install FF3Cipher is through Composer:

composer require ivinco/crypto-ff3

Ensure your project's composer.json and the associated lock file are updated.

Usage

Basic Encryption & Decryption

use Ivinco\Crypto\FF3Cipher;

$key = "EF4359D8D580AA4F7F036D6F04FC6A94"; // Your encryption key
$tweak = "D8E7920AFA330A73"; // Your tweak

$cipher = new FF3Cipher($key, $tweak);

$plaintext = "1234567890";
$ciphertext = $cipher->encrypt($plaintext);
echo "Ciphertext: " . $ciphertext . PHP_EOL;

$decrypted = $cipher->decrypt($ciphertext);
echo "Decrypted: " . $decrypted . PHP_EOL;

Using Custom Alphabets

In some scenarios, you might want to work with non-standard characters. This library supports encryption and decryption using custom alphabets:

$alphabet = "abcdefghijklmnopqrstuvwxyz"; // Custom alphabet
$cipher = FF3Cipher::withCustomAlphabet($key, $tweak, $alphabet);

$plaintext = "wfmwlrorcd";
$ciphertext = $cipher->encrypt($plaintext);
echo "Ciphertext: " . $ciphertext . PHP_EOL; // ywowehycyd

$decrypted = $cipher->decrypt($ciphertext); // wfmwlrorcd
echo "Decrypted: " . $decrypted . PHP_EOL;

Tests

The library is accompanied by unit tests.

Install the required packages via Composer:

composer install

Execute PHPUnit:

./vendor/bin/phpunit

Links

For FF3 implementations in other languages, you can refer to:

• Python Version
• Node.js Version
• Java Version
• C Version

For more information about FF3, you can refer to:

• https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38Gr1-draft.pdf
• https://csrc.nist.gov/CSRC/media/Projects/Cryptographic-Standards-and-Guidelines/documents/examples/FF3samples.pdf