README

Halite 是一个高级加密接口，它依赖于 libsodium 进行所有底层加密操作。

Halite 由 Paragon Initiative Enterprises 创建，这是我们持续改进生态系统并使 PHP中的加密 更安全、更易于实施的结果。

您可以在网上阅读 Halite 文档。

Halite 在 Mozilla 公共许可证 2.0 下发布。如果您希望在不将您的衍生作品置于 MPL 条款下使用的情况下扩展 Halite，Paragon Initiative Enterprises 也提供商业许可。

如果您对 MPL 软件作为后端 Web 应用程序的条件满意，但希望为使用 Halite 的应用程序购买支持合同，Paragon Initiative Enterprises 也提供此类支持。

重要：Halite 的早期版本在 GNU 公共许可证版本 3 (GPLv3) 下可用。只有 Halite 4.0.1 及更新版本在 Mozilla 公共许可证条款下可用。

安装 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, EncryptionKey): HiddenString
    • Symmetric\Crypto::decryptWithAD(string, EncryptionKey, string): HiddenString
  • 非对称
    • 匿名
      • Asymmetric\Crypto::seal(HiddenString, EncryptionPublicKey): string
      • Asymmetric\Crypto::unseal(string, EncryptionSecretKey): HiddenString
    • 认证
      • Asymmetric\Crypto::encrypt(HiddenString, EncryptionSecretKey, EncryptionPublicKey): string
      • Asymmetric\Crypto::encryptWithAD(HiddenString, EncryptionSecretKey, EncryptionPublicKey, string): string
      • Asymmetric\Crypto::decrypt(string, EncryptionSecretKey, EncryptionPublicKey): HiddenString
      • Asymmetric\Crypto::decryptWithAD(string, EncryptionSecretKey, EncryptionPublicKey, string): HiddenString
• 身份验证
  • 对称
    • Symmetric\Crypto::authenticate(string, AuthenticationKey): string
    • Symmetric\Crypto::verify(string, AuthenticationKey, string): bool
  • 非对称
    • Asymmetric\Crypto::sign(string, SignatureSecretKey): string
    • Asymmetric\Crypto::verify(string, SignaturePublicKey, string): bool

示例：加密和解密消息

首先，生成并持久化密钥一次

<?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致命错误：未捕获SodiumException：这尚未实现，因为从PHP中安全地擦除内存是不可能的

解决这个问题的方法是确保安装/启用了libsodium。请参阅本README中的上述内容以获取更多信息。

支持合同

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