README

AES 对称认证加密、密码哈希、HMAC 签名与 RSA 非对称加密的统一加密组件，零 Composer 依赖的纯库实现（仅依赖 ext-openssl）。CBC 模式采用 Encrypt-then-MAC，GCM 模式自带 AEAD 认证。

环境要求

PHP >= 8.3
ext-openssl

安装

composer require fiberphp/encryption

快速开始

对称加密（AES）

use FiberPHP\Encryption\Encrypter;
use FiberPHP\Encryption\KeyGenerator;

// 生成密钥（Base64 编码）
$key = KeyGenerator::generateKey('AES-256-CBC');

$enc = new Encrypter($key, 'AES-256-CBC');

// 加密（返回 Base64 字符串，支持字符串 / 数组）
$cipher = $enc->encrypt(['user_id' => 1, 'role' => 'admin']);

// 解密（返回原始数据，JSON 自动还原为数组）
$data = $enc->decrypt($cipher);

密码哈希

use FiberPHP\Encryption\Hasher;

$hasher = new Hasher();  // 默认 bcrypt

$hash = $hasher->make('user-password');
$hasher->check('user-password', $hash);          // true
$hasher->needsRehash($hash);                    // 算法升级时返回 true

// 切换 argon2id（需 PHP 编译启用 argon2）
$hasher = new Hasher(PASSWORD_ARGON2ID, ['memory_cost' => 65536, 'time_cost' => 4]);

HMAC 签名

use FiberPHP\Encryption\Signer;

$signer = new Signer('your-hmac-secret', 'sha256');

$signature = $signer->sign('data-to-sign');        // Base64
$signer->verify('data-to-sign', $signature);       // true（恒定时间比较）

RSA 非对称加密

use FiberPHP\Encryption\Rsa\PublicKey;
use FiberPHP\Encryption\Rsa\PrivateKey;

// 生成密钥对
[$privatePem, $publicPem] = KeyGenerator::generateRsaKeyPair(2048);

// 公钥加密 / 私钥解密
$publicKey = new PublicKey($publicPem);
$cipher = $publicKey->encrypt('敏感数据');

$privateKey = new PrivateKey($privatePem);
$plain = $privateKey->decrypt($cipher);

// 私钥签名 / 公钥验签（PrivateKey 实现 SignerInterface，可与 HMAC Signer 互换）
$signature = $privateKey->sign('data-to-sign');
$publicKey->verify('data-to-sign', $signature); // true

配置说明

Encrypter 支持算法：AES-128-CBC、AES-256-CBC、AES-128-GCM、AES-256-GCM。

密文结构：

模式	结构（Base64 解码后）
CBC（Encrypt-then-MAC）	`[IV 16B][HMAC-SHA256 32B][密文]`
GCM（AEAD）	`[IV 12B][Tag 16B][密文]`

KeyGenerator 还提供以下静态方法：

use FiberPHP\Encryption\KeyGenerator;

KeyGenerator::generateRawKey('AES-256-GCM');      // 原始二进制密钥（不做 Base64 编码）
KeyGenerator::validateKey($key, 'AES-256-CBC');   // 校验密钥长度是否匹配（raw 或 Base64 均可），返回 bool

// PBKDF2 从密码派生密钥（迭代次数建议不少于 100000，盐值建议不少于 16 字节）
$derived = KeyGenerator::deriveFromPassword($password, $salt, 'AES-256-CBC', 100000);

RSA 明文长度受密钥位数与 padding 限制（如 2048 位密钥 PKCS1 最多加密 245 字节），大数据量请采用「RSA 加密 AES 密钥 + AES 加密数据」的混合方案。

错误处理

所有失败均抛出异常，命名空间 FiberPHP\Encryption\Exception：

异常	触发场景
`EncryptionException`	算法/密钥配置错误、加密与签名失败（继承 `RuntimeException`）
`DecryptException`	解密失败：密文被篡改、MAC/Tag 认证失败、密钥不匹配（继承 `EncryptionException`）

use FiberPHP\Encryption\Exception\DecryptException;

try {
    $data = $enc->decrypt($payload);
} catch (DecryptException $e) {
    // 密文不可信或密钥错误，按认证失败处理（勿向前端泄露具体原因）
}

注意 Hasher::check()、Signer::verify()、Rsa\PublicKey::verify() 等验证类方法返回 bool，不抛异常。

特性

能力	说明
Encrypt-then-MAC	CBC 模式先加密再认证，密文篡改在 MAC 阶段被拒
AEAD	GCM 模式 OpenSSL 原生认证，无额外 HMAC
密码哈希	bcrypt / argon2i / argon2id，自包含算法元信息
算法升级	`needsRehash` 检测旧哈希并静默升级
接口抽象	`EncrypterInterface` / `HasherInterface` / `SignerInterface`，业务按接口注入
RSA 密钥对	`generateRsaKeyPair` 一键生成，私钥实现 `SignerInterface` 可替换 HMAC

fiberphp / encryption

Package info

Security

Statistics