# gmssl-client

**Repository Path**: random-ghost_admin/gmssl-client

## Basic Information

- **Project Name**: gmssl-client
- **Description**: gmssl客户端http请求插件
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-06
- **Last Updated**: 2026-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GMSSL Server PHP SDK

> 国密算法服务 PHP 客户端工具包，支持 SM2/SM3/SM4 密码运算、密钥管理（托管签名/解密）、审计日志
>
> **GM/T 0030 合规**：SM2 私钥不出境，签名/解密通过 key_id 托管完成，私钥永不在 API 响应中返回。

## 环境要求

- PHP >= 8.1
- ext-curl
- ext-json

## 安装

### Composer 安装

```bash
composer require random-ghost/gmssl-client 
```

### 手动引入（无 Composer）

```php
require_once 'src/GmsslClient.php';
require_once 'src/GmsslException.php';
require_once 'src/GmsslResponse.php';
require_once 'src/SM2.php';
require_once 'src/SM3.php';
require_once 'src/SM4.php';
require_once 'src/KeyManagement.php';
require_once 'src/Audit.php';
```

## 快速开始

```php
use Gmssl\GmsslClient;
use Gmssl\SM4;

// 密码操作客户端（公钥验签/加密、SM3、SM4）
$crypto = new GmsslClient('http://localhost:21210', 'gmssl-crypto-key-2026');

// 管理操作客户端（密钥管理、托管签名/解密）
$admin = new GmsslClient('http://localhost:21210', 'gmssl-admin-key-2026');

// SM3 哈希
$hash = $crypto->sm3()->hash('hello world');

// SM4 加密
$key = SM4::generateKey();
$iv  = SM4::generateIV();
$cipher = $crypto->sm4()->encryptCBC($key, $iv, '敏感数据');
$plain  = $crypto->sm4()->decryptCBC($key, $iv, $cipher);

// SM2 托管密钥：创建 → 签名 → 验签
$km = $admin->keyManagement();
$keyInfo = $km->create('my-key', 'sm2', '签名密钥');
$sig = $km->sign($keyInfo['id'], '待签名数据');              // 托管签名
$valid = $crypto->sm2()->verify($keyInfo['public_key'], '待签名数据', $sig);  // 公钥验签

// SM2 托管密钥：加密 → 解密
$cipher = $crypto->sm2()->encrypt($keyInfo['public_key'], '机密数据');
$plain  = $km->decrypt($keyInfo['id'], $cipher);             // 托管解密
```

## API 参考

### GmsslClient 主类

```php
$client = new GmsslClient(
    string $baseUrl,      // 服务地址
    string $apiKey,       // API Key
    int $timeout = 30,    // 请求超时
    array $headers = []   // 额外 HTTP 头
);
```

#### 模块访问

| 方法 | 返回 | 说明 | 所需权限 |
|------|------|------|---------|
| `sm2()` | `SM2` | 公钥验签/加密 | sm2 |
| `sm3()` | `SM3` | 密码杂凑 | sm3 |
| `sm4()` | `SM4` | 对称加密 | sm4 |
| `keyManagement()` | `KeyManagement` | 密钥管理 + 托管签名/解密 | keymgmt (admin) |
| `audit()` | `Audit` | 审计日志 | audit (admin) |

#### 系统方法

| 方法 | 说明 |
|------|------|
| `healthCheck(): bool` | 健康检查（免认证） |
| `version(): array` | 获取版本信息（免认证） |

### SM2 模块（公钥操作）

```php
$sm2 = $client->sm2();
```

| 方法 | 参数 | 返回 | 说明 |
|------|------|------|------|
| `verify($pubKey, $data, $sig)` | PEM 公钥, 原始数据, Base64 签名 | bool | 公钥验签 |
| `encrypt($pubKey, $plain)` | PEM 公钥, 原始明文 | Base64 密文 | 公钥加密 |

> 签名和解密请使用 `KeyManagement` 模块的 `sign()` 和 `decrypt()` 方法（托管模式，GM/T 0030 合规）。

### SM3 模块

```php
$sm3 = $client->sm3();
```

| 方法 | 参数 | 返回 | 说明 |
|------|------|------|------|
| `hash($data)` | 原始数据 | 64 字符十六进制 | SM3 哈希 |
| `hmac($key, $data)` | 密钥, 数据 | 64 字符十六进制 | SM3 HMAC |
| `pbkdf2($data, $salt, $iterations)` | 数据,密钥,迭代次数 | 64 字符十六进制 | SM3 HMAC |
| `verifyHash($data, $hash)` | 数据, 期望哈希 | bool | 验证哈希 |
| `verifyHmac($key, $data, $hmac)` | 密钥, 数据, 期望 HMAC | bool | 验证 HMAC |
| `verifyPbkdf2($data, $salt, $iterations, $expectedDerivedKey)` | 数据,密钥,迭代次数, 期望 HMAC | bool | 验证 PBKDF2 |

### SM4 模块

```php
$sm4 = $client->sm4();
```

| 方法 | 参数 | 返回 | 说明 |
|------|------|------|------|
| `encrypt($key, $data, $mode, $iv)` | 密钥, 明文, 模式, IV | Base64 密文 | 加密 |
| `decrypt($key, $cipher, $mode, $iv)` | 密钥, 密文, 模式, IV | 原始明文 | 解密 |
| `encryptCBC($key, $iv, $data)` | - | Base64 密文 | CBC 快捷加密 |
| `decryptCBC($key, $iv, $cipher)` | - | 原始明文 | CBC 快捷解密 |
| `encryptECB($key, $data)` | - | Base64 密文 | ECB 快捷加密 |
| `decryptECB($key, $cipher)` | - | 原始明文 | ECB 快捷解密 |
| `SM4::generateKey()` | - | 16 字节随机密钥 | 生成密钥 |
| `SM4::generateIV()` | - | 16 字节随机 IV | 生成 IV |

**模式常量**：`SM4::MODE_CBC` / `SM4::MODE_ECB` / `SM4::MODE_CFB` / `SM4::MODE_OFB`

### KeyManagement 模块（密钥管理 + 托管运算）

```php
$km = $admin->keyManagement();
```

| 方法 | 参数 | 返回 | 说明 |
|------|------|------|------|
| `create($name, $usage, $desc, $expires)` | 名称, sm2/sm4, 描述, 有效期秒 | `['id', 'name', 'usage', 'public_key']` | 创建密钥 |
| `import($name, $privKey, $desc, $expires)` | 名称, PEM 私钥, 描述, 有效期 | `['id', 'name', 'usage', 'public_key']` | 导入密钥 |
| `list()` | - | `['keys' => [...], 'total']` | 列出密钥 |
| `get($id)` | 密钥 ID | 密钥详情 | 获取详情 |
| `sign($id, $data)` | 密钥 ID, 原始数据 | Base64 签名 | 托管签名 |
| `decrypt($id, $cipher)` | 密钥 ID, Base64 密文 | 原始明文 | 托管解密 |
| `exportPublicKey($id)` | 密钥 ID | PEM 公钥 | 导出公钥 |
| `disable($id)` | 密钥 ID | `'disabled'` | 禁用密钥 |
| `enable($id)` | 密钥 ID | `'active'` | 启用密钥 |
| `archive($id)` | 密钥 ID | `'archived'` | 归档密钥 |
| `destroy($id)` | 密钥 ID | `'destroyed'` | 销毁密钥 |

### Audit 模块

```php
$audit = $admin->audit();
```

| 方法 | 参数 | 返回 | 说明 |
|------|------|------|------|
| `query($operation, $apiKey, $limit)` | 操作类型, Key 过滤, 条数 | `['entries' => [...], 'total']` | 查询审计日志 |
| `verify()` | - | `['valid' => bool, 'error' => string]` | 验证审计链 |
| `isChainValid()` | - | bool | 审计链是否完整 |

## 错误处理

所有 API 错误通过 `GmsslException` 抛出：

```php
use Gmssl\GmsslException;

try {
    $hash = $client->sm3()->hash('');
} catch (GmsslException $e) {
    echo "错误码: " . $e->getApiCode();    // 1003
    echo "错误信息: " . $e->getMessage();   // data is required

    // 便捷判断
    if ($e->isUnauthorized()) { /* 401 */ }
    if ($e->isForbidden()) { /* 403 */ }
    if ($e->isInvalidParam()) { /* 1003 */ }
    if ($e->isRateLimited()) { /* 429 */ }
}
```

## 完整示例

运行示例前请确保 GMSSL Server 已启动：

```bash
# 启动服务
./bin/gmssl-server.exe

# 运行示例
cd php-sdk
composer install   # 首次需要
php examples/demo.php
```

## 项目结构

```
php-sdk/
├── composer.json
├── README.md
├── src/
│   ├── GmsslClient.php       # 主客户端
│   ├── GmsslException.php    # 异常类
│   ├── GmsslResponse.php     # 响应封装
│   ├── SM2.php               # SM2 公钥操作（验签/加密）
│   ├── SM3.php               # SM3 密码杂凑
│   ├── SM4.php               # SM4 对称加密
│   ├── KeyManagement.php     # 密钥管理 + 托管签名/解密
│   └── Audit.php             # 审计日志
└── examples/
    └── demo.php              # 完整示例
```

## 合规说明

本 SDK 对接的 GMSSL Server 符合以下政务密码管理规范：

- **GM/T 0002** SM4 分组密码算法
- **GM/T 0003** SM2 椭圆曲线公钥密码算法
- **GM/T 0004** SM3 密码杂凑算法
- **GM/T 0030** 密钥管理技术规范（私钥不出境，托管签名/解密）
- **GM/T 0054** 密码应用安全要求（身份鉴别、安全审计）

## License

MIT