README

注意！此库不再维护。

欢迎使用Colloportus，一个密码哈希和数据加密库！
此库可用于哈希密码，以及加密需要解密的数据。它封装了Authenticated Encryption中的Bcrypt-SHA384。Paragon Initiative Enterprises的Password Lock的简化分支。
集成了Defuse PHP Encryption的部分功能，用于认证对称密钥加密。
依赖于Oirë Base64，用于将二进制数据编码为可存储的格式。

关于名称

Colloportus是著名哈利波特系列中的一道魔法咒语。它以一种非常难以打开的方式锁上门，对于麻瓜（即非魔法师的人来说）来说，这样的门是完全无法打开的。我决定将这个名称用于我的PasswordLock简化分支。
方法名称也进行了简化：lock、check和flip代替了HashAndEncrypt、DecryptAndVerify和RotateKey。

要求

需要PHP 7.3或更高版本，且启用mbString和openSSL。

安装

通过Composer安装

composer require oire/colloportus

运行测试

在项目目录中运行./vendor/bin/phpunit。

与早期PHP版本的兼容性

如果您需要与PHP 7.1.2兼容的版本，请安装版本1。

composer require "oire/colloportus ^1"

用法示例

哈希和加密密码

use Oire\Colloportus\Colloportus;
use Oire\Colloportus\Exception\ColloportusException;

// Actually you need to create a key beforehand and save it somewhere, for example, in a .env file
$key = Colloportus::createKey();

if (!empty($_POST['password'])) {
    try {
        $storeMe = Colloportus::lock($_POST['password'], $key);
    } catch (ColloportusException $e) {
        // Handle errors
    }
}

解密和验证密码

if (!empty($_POST['password'])) {
    try {
        $verified = Colloportus::check($_POST['password'], $storeMe, $key);
    } catch (ColloportusException $e) {
        // Handle errors
    }

    if ($verified) {
        // Success!
	}
}

加密一些需要解密的数据

注意！不要使用此功能处理密码，密码不得可逆解密。如果您要存储密码，必须对其进行哈希处理（见上文）。

$data = 'Mischief managed!';
$encrypted = Colloportus::encrypt($data, $key);
$decrypted = Colloportus::decrypt($encrypted, $key);
var_export($decrypted === $data);
// => true

使用不同的加密密钥重新加密数据

$newKey = Colloportus::createKey();

try {
    $newHash = Colloportus::flip($storeMe, $key, $newKey);
} catch (ColloportusException $e) {
    // Handle errors
}

错误处理

Colloportus在失败时会抛出各种异常

一个通用的ColloportusException，总是安全地捕获。所有其他异常都继承自它；
EncryptionException在数据加密失败时抛出；
DecryptionException在数据解密失败时抛出；
PasswordException在密码相关的调用失败时抛出；
KeyException在任何密钥相关的调用失败时抛出。

方法

所有Colloportus方法都是公开和静态的，因此不需要类实例。这些方法在代码注释中有说明，但以下是它们的描述仅供参考。
我们建议将每个调用都包裹在try...catch中，因为Colloportus在出错时会抛出ColloportusException。

public static function createKey(): string — 创建一个随机的加密密钥。返回一个可存储、可读的随机密钥。
public static function encrypt(string $plainText, string $key): string — 使用给定的密钥加密给定的字符串数据。返回加密数据。
public static function decrypt(string $cipherText, string $key): string — 使用给定的密钥解密给定的密文。返回解密后的明文。
public static function lock(string $password, string $key): string — 使用给定的密钥锁定给定的密码。返回可存储的结果。
public static function check(string $password, string $cipherText, string $key): bool — 验证给定的密码是否与给定的密文匹配。成功时返回true，失败时返回false。
public static function flip(string $cipherText, string $oldKey, string $newKey): string — 允许使用不同的密钥重新加密任何加密数据（例如，如果旧密钥已泄露且哈希值不可用）。返回使用新密钥加密的数据。
public static function keyIsValid(string $key): bool — 检查给定的密钥是否有效。由于密钥是随机的，基本检查密钥的长度以及它是否可以从Oirë的Base64实现解码。如果密钥有效，则返回true，否则返回false。

密码锁定与Colloportus之间的区别

提供了所有加密/解密所需的函数，以及哈希/验证方法。
删除了对旧PHP版本的回退，因此需要PHP 7.1.2（在特定版本中添加了hash_hkdf()方法）。
删除了自定义字符串处理实现，需要mbstring。
删除了版本头检查。
encrypt()和随后的Lock()返回URL/文件名安全的Base64数据，而不是十六进制。
所有sha256实例都改为sha384。
代码风格已更改，以符合Oirë标准。

贡献

欢迎所有贡献。请分支、创建功能分支、修改代码、运行测试、推送您的分支并发送pull请求。

oire / colloportus

维护者

详细信息