PHPackages                             xgrug/laravel-gm-crypto - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Security](/categories/security)
4. /
5. xgrug/laravel-gm-crypto

ActiveLibrary[Security](/categories/security)

xgrug/laravel-gm-crypto
=======================

Laravel extension package for Chinese National Cryptographic Algorithm SM3/SM4

v1.0.0(5mo ago)15MITPHPPHP ^8.0|^8.1|^8.2

Since Dec 10Pushed 5mo agoCompare

[ Source](https://github.com/xgrug/laravel-gm-crypto)[ Packagist](https://packagist.org/packages/xgrug/laravel-gm-crypto)[ RSS](/packages/xgrug-laravel-gm-crypto/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (4)Versions (2)Used By (0)

laravel-gm-crypto 国密算法扩展包
=========================

[](#laravel-gm-crypto--国密算法扩展包)

Laravel 国密算法（SM3/SM4）扩展包，支持 SM3 哈希算法和 SM4 对称加密算法。

[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP Version](https://camo.githubusercontent.com/c5e8da782b1a0673c08b4f474108036d2cc973470eed2d5d89d48e8c8475eee6/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e322d626c75652e737667)](https://php.net)[![Laravel Version](https://camo.githubusercontent.com/b1bd72841a248e7b11dc1fe58ad6b322129d2bbee535a6eef1e5c1d6f913cd95/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d25334525334431322e302d7265642e737667)](https://laravel.com)

特性
--

[](#特性)

- ✅ **SM3 哈希算法**：支持标准 SM3 和 HMAC-SM3
- ✅ **SM4 对称加密**：支持 ECB、CBC 等多种模式
- ✅ **灵活配置**：支持通过配置文件或环境变量配置
- ✅ **多种编码**：支持 Base64、十六进制等多种输出格式
- ✅ **Facade 支持**：提供便捷的 Facade 调用方式
- ✅ **依赖注入**：支持 Laravel 依赖注入
- ✅ **驱动管理**：采用 Laravel Manager 模式，易于扩展

安装
--

[](#安装)

通过 Composer 安装：

```
composer require xgrug/laravel-gm-crypto
```

发布配置文件（可选）：

```
php artisan vendor:publish --tag=gmcrypto-config
```

配置
--

[](#配置)

### 环境变量配置

[](#环境变量配置)

在 `.env` 文件中添加配置：

```
# 默认驱动
GM_CRYPTO_DRIVER=sm4

# SM4 配置
GM_SM4_KEY=0123456789abcdeffedcba9876543210
GM_SM4_MODE=CBC
GM_SM4_IV=fedcba98765432100123456789abcdef
GM_SM4_PADDING=none

# SM3 配置
GM_SM3_HMAC=false
GM_SM3_HMAC_KEY=
```

### 配置文件

[](#配置文件)

配置文件位于 `config/gmcrypto.php`：

```
return [
    'default' => env('GM_CRYPTO_DRIVER', 'sm4'),

    'sm4' => [
        'key' => env('GM_SM4_KEY', '0123456789abcdeffedcba9876543210'),
        'mode' => env('GM_SM4_MODE', 'CBC'),
        'iv' => env('GM_SM4_IV', 'fedcba98765432100123456789abcdef'),
        'padding' => env('GM_SM4_PADDING', 'pkcs7'),
    ],

    'sm3' => [
        'hmac' => env('GM_SM3_HMAC', false),
        'hmac_key' => env('GM_SM3_HMAC_KEY', ''),
    ],
];
```

使用方法
----

[](#使用方法)

### SM3 哈希算法

[](#sm3-哈希算法)

```
use Xgrug\LaravelGmCrypto\Facades\GmCrypto;

// 计算 SM3 哈希
$hash = GmCrypto::sm3Hash('abc');
// 输出: 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0

// 验证哈希
$isValid = GmCrypto::sm3Verify('abc', $hash);
// 返回: true

// HMAC-SM3
$hmac = GmCrypto::sm3Hmac('abc', 'secret-key');
```

### SM4 对称加密

[](#sm4-对称加密)

```
use Xgrug\LaravelGmCrypto\Facades\GmCrypto;

$plaintext = '0123456789abcdeffedcba9876543210';

// 加密（返回 Base64）
$encrypted = GmCrypto::sm4Encrypt($plaintext);

// 解密
$decrypted = GmCrypto::sm4Decrypt($encrypted);

// 十六进制格式
$encryptedHex = GmCrypto::sm4EncryptHex($plaintext);
$decryptedHex = GmCrypto::sm4DecryptHex($encryptedHex);
```

### 在控制器中使用

[](#在控制器中使用)

```
use Xgrug\LaravelGmCrypto\GmCryptoManager;

class UserController extends Controller
{
    public function __construct(
        private GmCryptoManager $crypto
    ) {}

    public function store(Request $request)
    {
        $encryptedData = $this->crypto->sm4Encrypt($request->sensitive_data);

        User::create([
            'data' => $encryptedData
        ]);
    }
}
```

### 在 Model 中自动加密

[](#在-model-中自动加密)

```
use Illuminate\Database\Eloquent\Model;
use Xgrug\LaravelGmCrypto\Facades\GmCrypto;

class User extends Model
{
    // 自动加密
    public function setPhoneAttribute($value)
    {
        $this->attributes['phone'] = GmCrypto::sm4Encrypt($value);
    }

    // 自动解密
    public function getPhoneAttribute($value)
    {
        return GmCrypto::sm4Decrypt($value);
    }
}
```

### 直接使用驱动

[](#直接使用驱动)

```
// 使用 SM3 驱动
$sm3 = GmCrypto::driver('sm3');
$hash = $sm3->hash('数据');

// 使用 SM4 驱动
$sm4 = GmCrypto::driver('sm4');
$encrypted = $sm4->encrypt('明文');
```

### 自定义配置

[](#自定义配置)

```
use Xgrug\LaravelGmCrypto\SM3;

$sm3 = new SM3();

$encrypted = $sm3->hash('abc');
```

```
use Xgrug\LaravelGmCrypto\SM4;

$sm4 = new SM4([
    'key' => '自定义密钥',
    'mode' => 'ECB',
    'padding' => 'pkcs7'
]);

$encrypted = $sm4->encryptBase64('明文');
```

API 文档
------

[](#api-文档)

### SM3 类

[](#sm3-类)

#### 方法

[](#方法)

- `hash(string $message): string` - 计算 SM3 哈希
- `hmac(string $message, string $key): string` - 计算 HMAC-SM3
- `verify(string $message, string $hash): bool` - 验证哈希值

### SM4 类

[](#sm4-类)

#### 方法

[](#方法-1)

- `encrypt(string $plaintext): string` - 加密（返回二进制）
- `decrypt(string $ciphertext): string` - 解密
- `encryptBase64(string $plaintext): string` - 加密并返回 Base64
- `decryptBase64(string $ciphertext): string` - 解密 Base64 字符串
- `encryptHex(string $plaintext): string` - 加密并返回十六进制
- `decryptHex(string $ciphertext): string` - 解密十六进制字符串

#### 支持的加密模式

[](#支持的加密模式)

- `ECB` - 电子密码本模式
- `CBC` - 密码块链接模式（推荐）

#### 支持的填充方式

[](#支持的填充方式)

- `pkcs7` - PKCS#7 填充（推荐）
- `zero` - 零填充

实际应用场景
------

[](#实际应用场景)

### 1. 敏感数据加密存储

[](#1-敏感数据加密存储)

```
// 加密用户身份证号、手机号等敏感信息
$user->id_card = GmCrypto::sm4Encrypt($request->id_card);
$user->phone = GmCrypto::sm4Encrypt($request->phone);
```

### 2. 数据完整性校验

[](#2-数据完整性校验)

```
// 生成数据签名
$data = ['user_id' => 123, 'amount' => 1000];
$signature = GmCrypto::sm3Hash(json_encode($data));

// 验证签名
if (GmCrypto::sm3Verify(json_encode($data), $signature)) {
    // 数据未被篡改
}
```

### 3. API 接口签名

[](#3-api-接口签名)

```
// 中间件验证请求签名
public function handle(Request $request, Closure $next)
{
    $signature = $request->header('X-Signature');
    $payload = $request->getContent();

    if (!GmCrypto::sm3Verify($payload, $signature)) {
        return response()->json(['error' => '签名验证失败'], 403);
    }

    return $next($request);
}
```

安全建议
----

[](#安全建议)

1. **密钥管理**：不要在代码中硬编码密钥，使用环境变量存储
2. **定期更换密钥**：建议定期更换加密密钥
3. **使用 CBC 模式**：相比 ECB 模式更安全
4. **HTTPS 传输**：加密数据在传输时仍需使用 HTTPS
5. **密钥长度**：SM4 密钥必须为 128 位（32 位十六进制字符）

依赖要求
----

[](#依赖要求)

- PHP >= 8.2
- Laravel >= 10
- OpenSSL 扩展

性能优化
----

[](#性能优化)

- SM3/SM4 算法采用纯 PHP 实现，性能略低于原生扩展
- 建议在高并发场景下使用缓存减少重复计算
- 考虑使用 C 扩展（如 OpenSSL）以获得更好性能

测试
--

[](#测试)

```
composer test
```

贡献
--

[](#贡献)

欢迎提交 Pull Request 或报告问题。

许可证
---

[](#许可证)

MIT License

相关资源
----

[](#相关资源)

- [国密算法标准文档](http://www.gmbz.org.cn/)

更新日志
----

[](#更新日志)

### v1.0.0 (2024-12-10)

[](#v100-2024-12-10)

- 初始版本发布
- 支持 SM3 哈希算法
- 支持 SM4 对称加密算法
- 支持 ECB、CBC 模式
- 提供 Facade 和依赖注入支持

###  Health Score

35

—

LowBetter than 79% of packages

Maintenance73

Regular maintenance activity

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

154d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4bd38d9fe229171166869e5f0db02f5ba204a9c8f5390d20d01f667ce1c3bd36?d=identicon)[xgrug](/maintainers/xgrug)

---

Top Contributors

[![xgrug](https://avatars.githubusercontent.com/u/171661883?v=4)](https://github.com/xgrug "xgrug (5 commits)")

---

Tags

laravelcryptosm3sm4chinese-cryptographyguomi

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/xgrug-laravel-gm-crypto/health.svg)

```
[![Health](https://phpackages.com/badges/xgrug-laravel-gm-crypto/health.svg)](https://phpackages.com/packages/xgrug-laravel-gm-crypto)
```

###  Alternatives

[tzsk/otp

A secure, database-free One-Time Password (OTP) generator and verifier for PHP and Laravel.

241641.4k1](/packages/tzsk-otp)[dgtlss/warden

A Laravel package that proactively monitors your dependencies for security vulnerabilities by running automated composer audits and sending notifications via webhooks and email

8745.6k](/packages/dgtlss-warden)[ercsctt/laravel-file-encryption

Secure file encryption and decryption for Laravel applications

642.6k](/packages/ercsctt-laravel-file-encryption)[laragear/poke

Keep your forms alive, avoid TokenMismatchException by gently poking your Laravel app

2211.5k](/packages/laragear-poke)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)