random-ghost/gmssl-client

PHP SDK for GMSSL Server - SM2/SM3/SM4 cryptographic operations, key management, and audit logging

1.0.1 2026-08-07 14:38 UTC

Requires

• php: >=8.1
• ext-curl: *
• ext-json: *

MIT

• RandomGhost

• crypto
• gin
• sm2
• sm3
• sm4
• GmSSL
• 国密
• gov-crypto

Published on Packagist.org on 2026-08-07 15:02 UTC

README

国密算法服务 PHP 客户端工具包，支持 SM2/SM3/SM4 密码运算、密钥管理（托管签名/解密）、审计日志

GM/T 0030 合规：SM2 私钥不出境，签名/解密通过 key_id 托管完成，私钥永不在 API 响应中返回。

环境要求

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

安装

Composer 安装

composer require random-ghost/gmssl-client 

手动引入（无 Composer）

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';

快速开始

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 主类

$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 模块（公钥操作）

$sm2 = $client->sm2();

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

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

SM3 模块

$sm3 = $client->sm3();

方法	参数	返回	说明
hash($data)	原始数据	64 字符十六进制	SM3 哈希
hmac($key, $data)	密钥, 数据	64 字符十六进制	SM3 HMAC
verifyHash($data, $hash)	数据, 期望哈希	bool	验证哈希
verifyHmac($key, $data, $hmac)	密钥, 数据, 期望 HMAC	bool	验证 HMAC

SM4 模块

$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 模块（密钥管理 + 托管运算）

$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 模块

$audit = $admin->audit();

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

错误处理

所有 API 错误通过 GmsslException 抛出：

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 已启动：

# 启动服务
./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