README

为 Laravel 框架提供 SM3 国密哈希算法支持。

⚠️ 不适用于口令存储：SM3 是通用散列函数（同类还有 SHA-256），不是口令专用算法。它没有盐值和迭代，相同口令永远得到相同哈希，可直接对照彩虹表与 GPU 暴力破解。本包适用于数据摘要、校验、签名等场景；口令请使用 Laravel 内置的 bcrypt 或 argon2id 驱动。

特性

🔐 支持 SM3 国密哈希算法
🚀 无缝集成 Laravel Hashing 系统
✅ 完全兼容 Laravel 5.6 - 13.x
📦 自动服务提供者注册
🧪 包含完整的单元测试

系统要求

PHP >= 7.3
Laravel >= 5.6（支持到 13.x）

安装

使用 Composer 安装：

composer require wuwx/laravel-hashing-sm3

Laravel 5.5+ 会自动注册服务提供者，无需手动配置。

配置

方式一：设置为默认驱动

编辑 config/hashing.php 文件，将 driver 更改为 sm3：

'driver' => 'sm3',

方式二：按需使用

保持默认驱动不变，在需要时指定使用 SM3：

Hash::driver('sm3')->make($value);

使用示例

生成哈希值

use Illuminate\Support\Facades\Hash;

// 使用默认驱动（需先配置为 sm3）
$hash = Hash::make('password');

// 或显式指定 sm3 驱动
$hash = Hash::driver('sm3')->make('password');

验证哈希值

// 验证密码
if (Hash::check('password', $hash)) {
    // 密码正确
}

// 使用 sm3 驱动验证
if (Hash::driver('sm3')->check('password', $hash)) {
    // 密码正确
}

在用户认证中使用

以下仅演示驱动切换的写法，不建议把 SM3 作为口令哈希，详见文首的安全提示。

配置为默认驱动后，Laravel 的用户认证系统会自动使用 SM3 算法：

// 用户注册
$user = User::create([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'password' => Hash::make('secret'), // 自动使用 SM3
]);

// 用户登录验证
if (Hash::check($request->password, $user->password)) {
    // 登录成功
}

测试

运行测试套件：

composer test

或使用 PHPUnit：

vendor/bin/phpunit

依赖

本包使用 wuwx/sm3 作为底层 SM3 算法实现，纯 PHP、无扩展依赖。

从 2.x 升级

3.0.0 有三处不兼容改动，详见 CHANGELOG：

1. 全局函数 sm3() 不再可用（旧版由 ch4o5/sm3-php 间接提供）：

- $hash = sm3($value);
+ $hash = Wuwx\Sm3\Sm3::hash($value);

2. 空字符串的摘要值改变：修正为 GB/T 32905 标准值，旧的空串摘要需重新生成。

3. info() 返回值改变：algo 由 null 变为 'sm3'，依赖该字段判空的逻辑需调整。

已知限制

needsRehash() 恒返回 false：SM3 没有可调参数（不像 bcrypt 的 cost），格式正确即无需重算。因此 Laravel 登录时的自动重哈希机制不会生效，存量密码不会被自动升级。
Hash::isHashed() 依赖驱动的 info()：本驱动按 64 位十六进制格式识别 SM3 哈希，需 Laravel 11+ 才生效。Laravel 10.x 的 HashManager::isHashed() 硬编码 password_get_info()，无法识别自定义驱动，属框架限制。副作用：明文密码若恰好是 64 位十六进制串，会被 hashed cast 误判为已哈希而原样入库。
吞吐约 0.75 MB/s：底层是纯 PHP 实现（无扩展依赖，32 位与 64 位结果一致），短串足够快，但不要用它给大文件算摘要。

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request！

wuwx / laravel-hashing-sm3

Package info

Security

Statistics