FF3 - Python中的格式保留加密

这是NIST批准的FF3和FF3-1格式保留加密（FPE）算法在Python中的实现。

此软件包实现了2016年3月NIST出版物800-38G《格式保留加密方法》中描述的FF3算法，并在2019年2月28日对FF3-1进行了修订。

• NIST推荐SP 800-38G (FF3)
• NIST推荐SP 800-38G修订1 (FF3-1)

已在此软件包中实现了最小域大小和修订的调整长度更改，支持64位和56位调整。NIST仅发布了64位调整的官方测试向量，但已使用ACVP测试向量进行FF3-1的测试。预期最终NIST标准将提供56位调整长度的更新测试向量。

安装

pip3 install ff3

使用方法

FF3是一种Feistel密码，Feistel密码使用表示字母表的基数进行初始化。字母表中的字符数称为基数。以下是一些典型的基数值

• 基数10：数字0..9
• 基数36：0..9、a-z的字母数字
• 基数62：0..9、a-z、A-Z的字母数字

特殊字符和国际字符集，例如UTF-8中发现的，可以通过指定自定义字母表来支持。此外，明文字符串中的所有元素共享相同的基数。因此，由一个首字母后跟6位数字组成的识别号（例如A123456）在保持此约定的情况下不能被FPE正确加密。

输入明文的最大长度限制基于所选基数（2 * floor(96/log2(基数)))

• 基数10：56
• 基数36：36
• 基数62：32

为了解决字符串长度问题，可以将较长的文本分块进行编码。

密钥长度必须是128位、192位或256位。调整值是7个字节（FF3-1）或8个字节的原生FF3。

与任何加密包一样，管理和保护密钥至关重要。调整值通常不会被保密。此包在初始化加密器后不会在内存中存储密钥。

代码示例

以下示例代码使用默认域[0-9]，可以帮助您开始。

from ff3 import FF3Cipher

key = "2DE79D232DF5585D68CE47882AE256D6"
tweak = "CBD09280979564"
c = FF3Cipher(key, tweak)

plaintext = "3992520240"
ciphertext = c.encrypt(plaintext)
decrypted = c.decrypt(ciphertext)

print(f"{plaintext} -> {ciphertext} -> {decrypted}")

# format encrypted value
ccn = f"{ciphertext[:4]} {ciphertext[4:8]} {ciphertext[8:12]} {ciphertext[12:]}"
print(f"Encrypted CCN value with formatting: {ccn}")

CLI示例

此包安装了命令行脚本ff3_encrypt和ff3_decrypt，可以从Linux或Windows命令行运行。

% ff3_encrypt 2DE79D232DF5585D68CE47882AE256D6 CBD09280979564 3992520240
8901801106
% ff3_decrypt 2DE79D232DF5585D68CE47882AE256D6 CBD09280979564 8901801106
3992520240

自定义字母表

支持最多256个字符的自定义字母表。要使用由大写字母A-F（基数=6）组成的字母表，我们可以从上面的代码示例继续

c6 = FF3Cipher.withCustomAlphabet(key, tweak, "ABCDEF")
plaintext = "BADDCAFE"
ciphertext = c6.encrypt(plaintext)
decrypted = c6.decrypt(ciphertext)

print(f"{plaintext} -> {ciphertext} -> {decrypted}")

要求

该项目是用Python 3.8及更高版本构建和测试的。唯一的依赖项是PyCryptodome。

测试

本包使用NIST提供的官方测试向量进行测试，包括56位调整值的草案ACVP测试向量。

要运行此实现的单元测试，包括NIST规范中的所有测试向量，请运行以下命令

python3 -m ff3.ff3_test

性能基准

Mysto FF3在MacBook Air（1.1 GHz 四核Intel Core i5）上进行基准测试，每秒执行70,000次标记化操作，随机8字符数据输入。

要运行性能测试

python3 -m ff3.ff3_perf

FF3算法

FF3算法是一种基于八轮Feistel密码的调整密码。密码块加密在固定长度的比特组上操作，称为块。Feistel密码不是一个特定的密码，而是一个设计模型。此FF3 Feistel加密包括八个处理明文的轮次。每一轮应用一个内部函数或轮函数，然后是转换步骤。

FF3轮函数使用ECB模式的AES加密，该加密在每个迭代中对要加密的文本的交替部分进行。使用密钥值仅初始化AES密码。此后，使用调整值与中间加密文本一起作为轮函数的输入。

其他FPE算法

只有FF1和FF3被NIST批准用于格式保持加密。FF1有专利权，据说包括开源实现。鉴于2018年Hoang、Tessaro和Trieu在"The Curse of Small Domains: New Attacks on Format-Preserving Encryption"中提出的问题，对任何不是标准且未经公众审查的FPE应非常谨慎。

实现说明

此实现最初基于Capital One Go实现。它尽可能紧密地遵循NIST规范中概述的算法，包括命名。

FPE可用于对敏感数据进行数据标记化，这些数据可以进行加密逆转。此实现不提供有关PCI DSS或其他验证的任何保证。

虽然所有NIST和ACVP测试向量都通过，但此包尚未进行广泛的测试。

使用的加密库是用于AES加密的PyCryptodome。FF3使用单块加密，初始向量IV为0，实际上等同于ECB模式。AES ECB是唯一符合FF3规范要求的块加密函数。

在FF3-1中，域大小被修订为radix^minLen >= 1,000,000，并在ff3.py中通过常量DOMAIN_MIN表示。FF3-1处于草案状态。

在FF3Cipher构造函数中需要指定调整值，但在每次encrypt和decrypt调用中可以可选地覆盖它。这类似于在创建加密器对象时传递IV或nonce。

开发者安装

要安装开发版本

git clone https://github.com/mysto/python-fpe.git
cd python-fpe
pip3 install --editable .

在贡献任何拉取请求之前，您需要首先分叉此存储库，并将远程原点更改以反映您的分叉

git remote set-url origin git@github.com:YOUR-GITHUB-USERNAME/python-fpe.git

作者

Brad Schoening

许可协议

本项目的许可条款为Apache 2.0许可协议。