# encryption-gm

**Repository Path**: fiberphp/encryption-gm

## Basic Information

- **Project Name**: encryption-gm
- **Description**: 🛡️ FiberPHP 国密加密 —— SM3/SM4 算法实现，符合国密标准，零框架依赖。
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-09-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FiberPHP 国密加密 (Encryption-GM)

国密 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`

## 安装

```bash
composer require fiberphp/encryption-gm
```

## 快速开始

### SM4 对称加密

```php
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 哈希

```php
use FiberPHP\EncryptionGm\Sm3;

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

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

### SM3 密码哈希

```php
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 的异常捕获逻辑：

```php
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 模式     |

## License

MIT License (c) 2026 庞斌，详见 [LICENSE](LICENSE)。