README

注意：这是版本1分支。请尽快升级到较新版本。

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

Halite是由Paragon Initiative Enterprises创建的，这是为了继续努力改善生态系统，并使PHP中的加密更安全、更容易实现。

它是在GPLv3许可证下发布的。如果您想在应用程序中使用Halite而不将源代码放在与GPL兼容的许可证下，可以从Paragon Initiative Enterprises获得商业许可证。

在您的应用程序中使用Halite

步骤1：安装libsodium

在您可以使用Halite之前，您必须选择一个适合您项目需求版本的libsodium。以下简要概述了可用版本的Halite的需求差异。

如果您计划使用Halite 1，或者您的发行版已经包含必要的版本，那么您应该能够安装预编译的libsodium包。

步骤2：安装PECL libsodium扩展

重要提示：每次安装不同版本的libsodium时，都需要重复此步骤。生成的PECL libsodium扩展依赖于当前安装的libsodium版本。

PECL libsodium扩展的安装说明可以在Paragon Initiative Enterprises网站上的PECL libsodium书籍中找到。

步骤3：使用Composer安装Halite

使用Halite的最后一步是使用Composer安装它。

对于Halite的最新版本

composer require guazi/halite

或者对于Halite的旧版本，指定版本号

composer require guazi/halite:^v1

在您的项目中使用Halite

查看文档。基本的Halite API设计得很简单

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

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

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

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

var_dump($decrypted === $message); // bool(true)

这将产生类似的结果

314202017d893cb20eeab4ef51f6861d55a60797c6de0453f11e464ce210091b914b1c40470869d3d390986eeebe2d34e393efe986fc52de7464f30d8d38df5c6b629c019c454a2eec03ca618f9e2ba34f20c81614d63988f0f845911cafbeee7e79893e1f7c33e298da3b3474ac3ea9181298a2ce7e468914c329b35f50ac32b01136dc87e7f7881d31909227273817ac01c3b8f19dc6db881ad962d5b3e4c95d61494747028114f15a2e718c19

示例：从密码生成密钥

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

$passwd = 'correct horse battery staple';
// Use random_bytes(32); to generate the salt:
$salt = "\xdd\x7b\x1e\x38\x75\x9f\x72\x86\x0a\xe9\xc8\x58\xf6\x16\x0d\x3b\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）的系统上加密大型文件（例如，千兆字节）。

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

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

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