Halite

Halite 是一个高级密码学接口，其所有底层密码学操作均依赖于 libsodium。

Halite 由 Paragon Initiative Enterprises 创建，这是我们为改善生态系统并让 PHP 中的密码学 更安全、更易于实现而持续努力的结果。

你可以在线阅读 Halite 文档。

Halite 根据 Mozilla Public License 2.0 发布。如果你希望在扩展 Halite 时不必让衍生作品遵循 MPL 条款，可获取商业许可证，由 Paragon Initiative Enterprises 提供。

如果你对用于后端 Web 应用程序的 MPL 软件条款感到满意，但想为使用 Halite 的应用程序购买支持合同，Paragon Initiative Enterprises 也提供此类服务。

重要提示： 早期版本的 Halite 根据 GNU Public License version 3 (GPLv3) 发布。只有 Halite 4.0.1 及更新版本才以 Mozilla Public License 条款提供。

安装 Halite

在开始使用 Halite 之前，你必须选择一个符合项目需求的版本。下面简要说明了 Halite 各可用版本在要求上的差异。

注意：Halite 5.0.x 可运行于 PHP 8.0，但性能不如在 PHP 8.1 上。

如果你需要 5.1 之前的 Halite 版本，请参阅与该特定分支相关的文档。

要安装 Halite，你首先需要安装 libsodium。 你可能需要也可能不需要 PHP 扩展。对大多数人来说，这意味着执行...

sudo apt-get install php7.2-sodium

...或与你操作系统和 PHP 版本相对应的等效命令。

如果你遇到困难，@aolko 贡献的这份分步指南 可能会有所帮助。

安装好必备组件后，通过 Composer 安装 Halite：

composer require paragonie/halite:^5

旧版 Halite 的商业支持

Halite 的免费支持仅涵盖最新的主版本（目前为 5）。

如果你的公司需要对旧版 Halite 的支持，请联系 Paragon Initiative Enterprises 咨询商业支持选项。

如果你需要一种简单的方法从旧版 Halite 迁移，请查看 halite-legacy。

在项目中使用 Halite

请查阅文档。Halite 的基础 API 设计以简洁为宗旨：

• 加密
  • 对称
    • Symmetric\Crypto::encrypt(HiddenString, EncryptionKey): string
    • Symmetric\Crypto::encryptWithAD(HiddenString, EncryptionKey, string): string
    • Symmetric\Crypto::decrypt(string, ):

示例：加密和解密消息

首先，生成并持久化保存一个密钥，且只需执行一次：

<?php
use ParagonIE\Halite\KeyFactory;

$encKey = KeyFactory::generateEncryptionKey();
KeyFactory::save($encKey, '/path/outside/webroot/encryption.key');

然后你可以像这样加密/解密消息：

<?php
use ParagonIE\Halite\KeyFactory;
use ParagonIE\Halite\Symmetric\Crypto as Symmetric;
use ParagonIE\HiddenString\HiddenString;

$encryptionKey = KeyFactory::loadEncryptionKey('/path/outside/webroot/encryption.key');

$message = new HiddenString('This is a confidential message for your eyes only.');
$ciphertext = Symmetric::encrypt($message, $encryptionKey);

$decrypted = Symmetric::decrypt($ciphertext, $encryptionKey);

var_dump($decrypted->getString() === $message->getString()); // bool(true)

这会生成类似如下的输出：

MUIDAEpQznohvNlQ-ZRk-ZZ59Mmox75D_FgAIrXY2cUfStoeL-GIeAe0m-uaeURQdPsVmc5XxRw3-2x5ZAsZH_es37qqFuLFjUI-XK9uG0s30YTsorWfpHdbnqzhRuUOI09c-cKrfMQkNBNm0dDDwZazjTC48zWikRHSHXg8NXerVDebzng1aufc_S-osI_zQuLbZDODujEnpbPZhMMcm4-SWuyVXcBPdGZolJyT

Halite 中的密码学密钥

重要提示：Halite 使用的是 Key 对象，而不是字符串。

如果你尝试 echo 一个密钥对象，你将得到一个空字符串，而不是其内容。如果你尝试 var_dump() 一个密钥对象，你只会得到关于该密钥类型的一些信息。

如果你想查看密钥的原始二进制内容，必须显式调用 $obj->getRawKeyMaterial()。在大多数用例中，不建议这样做。

示例：从密码生成密钥

<?php
use ParagonIE\Halite\KeyFactory;
use ParagonIE\HiddenString\HiddenString;

$passwd = new HiddenString('correct horse battery staple');
// Use random_bytes(16); to generate the salt:
$salt = "\xdd\x7b\x1e\x38\x75\x9f\x72\x86\x0a\xe9\xc8\x58\xf6\x16\x0d\x3b";

$encryptionKey = KeyFactory::deriveEncryptionKey($passwd, $salt);

从密码派生的密钥可以代替随机生成的密钥使用。

示例：在低内存系统上加密大文件

Halite 包含一个文件密码学类，它利用流式 API，使得在可用内存非常少（即小于 8 MB）的系统上也能加密大文件（例如数 GB）。

<?php
use ParagonIE\Halite\File;
use ParagonIE\Halite\KeyFactory;

$encryptionKey = KeyFactory::loadEncryptionKey('/path/outside/webroot/encryption.key');

File::encrypt('input.txt', 'output.txt', $encryptionKey);

常见支持问题

未捕获的 SodiumException：无法擦除内存

PHP Fatal error: Uncaught SodiumException: This is not implemented, as it is not possible to securely wipe memory from PHP

解决方法是确保已安装/启用 libsodium。有关更多信息，请参阅本 README 上文。

支持合同

如果你的公司在产品或服务中使用了这个库，你可能会对从 Paragon Initiative Enterprises 购买支持合同感兴趣。