README

国密 SM3/SM4 算法实现，零框架依赖的纯库（仅依赖 ext-openssl 与 fiberphp/encryption）。SM4 对称加密与 SM3 哈希均实现 FiberPHP\Encryption 的接口，可与 AES/bcrypt 互换。

环境要求

PHP >= 8.3
ext-openssl >= 1.1.1（需支持 SM3 / SM4 算法），可通过 Sm3::isSupported() / Sm4::isSupported() 运行时探测
fiberphp/encryption

安装

composer require fiberphp/encryption-gm

快速开始

SM4 对称加密

use FiberPHP\EncryptionGm\Sm4;

$key = base64_encode(random_bytes(16));  // SM4 密钥固定 128 位（16 字节）
$sm4 = new Sm4($key, 'CBC');              // 支持 CBC / GCM / CTR / CFB / OFB

$cipher = $sm4->encrypt(['user_id' => 1, 'name' => '张三']);
$data   = $sm4->decrypt($cipher);         // 原始数组

CBC / CTR / CFB / OFB 等非 AEAD 模式均采用 Encrypt-then-MAC，以 HMAC-SM3 认证，密文结构为 [IV 16B][HMAC-SM3 32B][密文]；GCM 模式自带 AEAD（IV 12B + Tag 16B）。

SM3 哈希

use FiberPHP\EncryptionGm\Sm3;

$hash = Sm3::hash('abc');
// 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0

$mac  = Sm3::hmac('data', 'secret-key');  // HMAC-SM3
$file = Sm3::hashFile('/path/to/file');   // 流式分块

SM3 密码哈希

use FiberPHP\EncryptionGm\Sm3Hasher;

$hasher = new Sm3Hasher(iterations: 10000);

$hash = $hasher->make('user-password');   // $sm3$10000$<base64-salt>$<base64-hash>
$hasher->check('user-password', $hash);   // true
$hasher->needsRehash($hash);              // 迭代次数变更时返回 true

配置说明

Sm4 构造参数：

参数	说明
`key`	16 字节密钥（支持 raw bytes 或 base64 编码字符串）
`mode`	加密模式：CBC / GCM / CTR / CFB / OFB（ECB 不安全不提供）

Sm3Hasher 哈希格式自包含元信息：$sm3$<iterations>$<base64-salt>$<base64-hash>，迭代次数建议 >= 10000。

错误处理

失败均抛出 FiberPHP\EncryptionGm\Exception\GmException（继承 fiberphp/encryption 的 EncryptionException）；解密失败抛出 FiberPHP\Encryption\Exception\DecryptException，可直接复用 fiberphp/encryption 的异常捕获逻辑：

use FiberPHP\Encryption\Exception\DecryptException;
use FiberPHP\EncryptionGm\Exception\GmException;

try {
    $data = $sm4->decrypt($payload);
} catch (DecryptException) {
    // 密文不可信或密钥错误（HMAC-SM3 认证失败）
} catch (GmException $e) {
    // 算法不支持、密钥/模式配置错误等
}

Sm3Hasher::check() / needsRehash() 返回 bool，不抛异常。

特性

能力	说明
SM4 多模式	CBC / CTR / CFB / OFB（均带 HMAC-SM3 认证）与 GCM（AEAD）
国密全栈	SM4 加密 + SM3 认证，符合 GB/T 32907 / GB/T 32905
接口互换	Sm4 实现 `EncrypterInterface`，Sm3Hasher 实现 `HasherInterface`，与 AES/bcrypt 零改动切换
环境探测	`Sm4::isSupported()` / `Sm3::isSupported()` 检测 OpenSSL 支持
AEAD 自检	部分 OpenSSL 列出 sm4-gcm 但无法实际加密，构造时探测，不支持则抛异常并提示使用 CBC 模式

fiberphp / encryption-gm

Package info

Security

Statistics