README

使用 open_ssl 的 PHP 数据加密器

目录

• 安装
• 使用方法
  • 基本使用
    • 加密
    • 解密
  • 高级使用
• 格式化器
  • 内置格式化器
    • Base64Formatter
    • HexFormatter
  • 创建自定义格式化器
• API
• 故障排除
  • 在 C# 应用中使用 HexFormatter
• 集成
• 开发 / 贡献
  • 安装生态系统
  • 测试
  • PHP CS Fixer
• 许可

安装

使用 composer 安装库

composer require nmure/encryptor "~1.0.0"

使用方法

基本使用

加密

使用此库的最简单方法是创建一个 Encryptor 实例，传入一个密钥和一个用于加密的密码方法。要查看您 PHP 安装支持的加密方法，请使用 openssl_get_cipher_methods 函数。

然后您可以对纯文本数据进行加密，例如：

use Nmure\Encryptor\Encryptor;

$encryptor = new Encryptor('452F93C1A737722D8B4ED8DD58766D99', 'AES-256-CBC');
$encrypted = $encryptor->encrypt('plain text data');

加密器除了使用密钥外，还使用初始化向量（IV）来加密数据。此 IV 是随机生成的，以确保使用相同密钥对相同数据进行两次加密不会产生相同的加密输出。

因此，您应该将用于加密数据的 IV 与加密数据一起存储，以便稍后能够解密。

例如，您可以在数据库中存储它：

| id |  iv  | encrypted |
-----------------------
| 1  | 945a | oifd4867h |
| 2  | 894d | 62vbyibd6 |

解密

然后，要解密数据，初始化加密器并调用 decrypt 函数

use Nmure\Encryptor\Encryptor;

$encryptor = new Encryptor('452F93C1A737722D8B4ED8DD58766D99', 'AES-256-CBC');
// retrieve the IV ($iv) and the encryped data ($encrypted) from your DB
// ...
$encryptor->setIv($iv);
$plainText = $encryptor->decrypt($encrypted);

高级使用

如果您不想处理加密数据和 IV 的存储方式，可以使用 格式化器。格式化器将 IV 和加密数据组合成一个字符串，以便更容易存储和与另一个应用程序共享。

例如，如果您想将加密数据存储到文件中，可以使用 Base64Formatter

use Nmure\Encryptor\Encryptor;
use Nmure\Encryptor\Formatter\Base64Formatter;

$encryptor = new Encryptor('452F93C1A737722D8B4ED8DD58766D99', 'AES-256-CBC');
$encryptor->setFormatter(new Base64Formatter());

// will produce a string containg the IV and the encrypted data
$encrypted = $encryptor->encrypt('plain text data');
// store $encrypted to a file

然后，要解密数据，使用相同的加密器/格式化器组合，只需调用带有组合字符串的 decrypt 函数

use Nmure\Encryptor\Encryptor;
use Nmure\Encryptor\Formatter\Base64Formatter;

$encryptor = new Encryptor('452F93C1A737722D8B4ED8DD58766D99', 'AES-256-CBC');
$encryptor->setFormatter(new Base64Formatter());

// get the encrypted data from a file, or whatever
// ... $encrypted

// the encryptor uses the formatter to get the IV used for the encryption from
// the given $encrypted string
$plainText = $encryptor->decrypt($encrypted);

如果您不想再使用格式化器，只需在加密器上将其设置为 null

$encryptor->setFormatter(null);

使用格式化器更方便，因为所有将 IV 与加密数据一起存储的工作都由格式化器完成，而不再是您的工作。

格式化器

格式化器用于将 IV 和加密数据组合成一个字符串（通常是非二进制字符串），以便更容易存储和跨系统共享。它们都实现了 FormatterInterface。

内置格式化器

Base64Formatter

在加密过程中，Base64Formatter 返回的字符串包含 base64 编码的 IV，连接到冒号（:），然后连接到 base64 编码的加密数据。

由于冒号不是 base64 字符集中的字符，我们可以轻松地将此字符串分为两部分，并在解密过程中获取 IV 和加密数据。

HexFormatter

在加密过程中，HexFormatter 返回的字符串包含连接的 IV 和加密数据二进制字符串的十六进制表示。

在解密过程中，此字符串被分割以获取 IV 和加密数据。我们使用密码方法的 IV 长度来确定如何分割此字符串。

创建自定义格式化器

当然，您可以根据自己的需求创建自己的格式化器，它只需实现 FormatterInterface。

API

• Nmure\Encryptor\Encryptor :
  • public string encrypt($data) : 加密给定的明文字符串并返回它。当将格式化器设置为加密器时，此函数的返回值是包含 IV 和加密数据的格式化字符串。
  • public string decrypt($data) : 解密给定的加密数据并返回它。当将格式化器设置为加密器时，给定数据必须是此格式化器格式化的字符串。将从格式化字符串中确定 IV。如果没有设置格式化器，IV 必须设置为加密器，以便能够解密给定数据。
  • public string generateIv() : 根据加密方法生成一个新的随机 IV，将其设置到加密器并返回它。
  • public void enableAutoIvUpdate() : 在每次加密过程之前启用自动 IV 更新，以确保相同的明文数据不会产生相同的输出。自动 IV 更新默认启用。
  • public void disableAutoIvUpdate() : 禁用每次加密过程之前的自动 IV 更新。加密将使用最后设置的 IV 或如果没有设置 IV，则生成一个。
  • public void turnHexKeyToBin() : 将十六进制密钥转换为二进制密钥。
  • public string getIv() : 返回加密器的 IV。
  • public void setIv($iv) : 将给定的 IV 设置到加密器。
  • public void setFormatter(FormatterInterface $formatter = null) : 将给定的 FormatterInterface 设置到加密器。要取消设置格式化器，将 null 传递到此函数。
• Nmure\Encryptor\Formatter\FormatterInterface :
  • public string format($iv, $encrypted) : 将给定的 IV 和加密数据格式化为字符串并返回它。
  • public array parse($input, $ivLength) : 解析给定的 $input 字符串，并返回包含 IV 和加密数据的数组。可以使用 $ivLength 参数解析 $input 字符串。

故障排除

在 C# 应用中使用 HexFormatter

如果您使用此格式化器与加密器共享与 C# 应用程序加密数据，您可能需要将您的密钥转换为二进制密钥。

use Nmure\Encryptor\Encryptor;
use Nmure\Encryptor\Formatter\HexFormatter;

$encryptor = new Encryptor('452F93C1A737722D8B4ED8DD58766D99', 'AES-256-CBC');
$encryptor->turnHexKeyToBin(); // turning the hex key to a binary key
$encryptor->setFormatter(new HexFormatter());

$encrypted = $encryptor->encrypt('plain text data');

集成

您可以将此库作为独立库使用，或者如果您正在使用 Symfony，它被封装在 NmureEncryptorBundle 中。

开发 / 贡献

安装生态系统

docker-compose run --rm composer install

测试

docker-compose run --rm phpunit -c /app

格式化器测试类应该扩展 AbstractFormatterTest 类，以确保格式化器满足最低要求。

PHP CS Fixer

docker-compose run --rm phpcs phpcbf --standard=PSR2 /scripts/

许可

此库根据 MIT 许可证授权。更多信息请参阅 LICENSE 文件。