pollux

package module
v0.2.10 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 25, 2026 License: MIT Imports: 0 Imported by: 0

README

pollux-go

Go 语言国密（GM）算法与协议集成工具包。所有核心算法由 github.com/emmansun/gmsm 提供，pollux-go 在其之上补充协议集成、SM2 感知的 X.509 处理、以及符合 Go 习惯的封装 API。

pollux-go 是集成工具包，不是密码学实现。它把 gmsm 的原语封装成协议层能力， 并对外暴露一致、Go 风格的 API。

能力矩阵

能力 包 状态 说明
SM2 签名 / 加密 / 密钥交换 sm2 ✅ 封装 gmsm/sm2
SM3 哈希 / HMAC / KDF / HKDF sm3 ✅ 封装 gmsm/sm3
SM4 分组密码（GCM/CBC/CTR/CFB） sm4 ✅ 封装 gmsm/sm4
SM9 基于身份加密 sm9 ✅ 封装 gmsm/sm9
ZUC 序列密码 zuc ✅ 封装 gmsm/zuc
SM2 感知 X.509 smx509、cert ✅ 证书创建 / 解析 / 验证
路线 A — 标准 TLS 1.3 tls13、http ✅ 生产 基于 crypto/tls
路线 A — 标准 QUIC quic ✅ 生产 基于 quic-go
路线 C — RFC 8998 TLS 1.3 GM tls13gm ✅ 互通已验证 完整握手引擎，与 Tongsuo/BabaSSL 互通（见 互通矩阵）
路线 C — RFC 9001 QUIC GM quicgm ✅ 互通已验证 transport-level packet protection，端到端 + 0-RTT 测试
TLCP 1.1（GB/T 38636-2020） tlcp ⚠️ 实验 基于 gotlcp，待第三方安全审计
国密套件注册 tls ✅ 仅套件 ID/名称注册，非完整 TLS

包结构

sm2 sm3 sm4 sm9 zuc           # 国密算法封装
smx509 cert                   # SM2 感知 X.509
gmstd                         # GM/T 标准辅助函数
tlcp                          # TLCP 1.1（GB/T 38636-2020）
tls13gm quicgm                # RFC 8998 / RFC 9001 GM 栈（Route C，已与 Tongsuo 互通验证）
tls tls13 quic                # 标准 TLS/QUIC（Route A）
http                          # TLS / TLCP / TLS1.3 HTTP 辅助
internal/memsecure            # 密钥材料安全清零
internal/panicsafe            # panic 安全辅助

快速上手

go get github.com/iuboy/pollux-go@latest

SM4-GCM 加解密（高级便捷封装，含一次性随机 nonce 与密钥清零）：

import "github.com/iuboy/pollux-go/sm4"

key, _ := sm4.GenerateKey()
defer sm4.ZeroKey(key)
// SealRandomNonce 自动生成随机 nonce 并随密文返回
sealed, _ := sm4.SealRandomNonce(key, plaintext, additionalData)
pt, _ := sm4.OpenWithNonce(key, sealed, additionalData)

标准 TLS 1.3 HTTP 服务（路线 A）：

import "github.com/iuboy/pollux-go/http"

srv, err := http.NewTLS13Server(opts)  // MinVersion 强制 TLS 1.3

各包的完整 API 见 godoc，设计背景见 文档。

构建与测试

make test         # 等价于 go test ./...
make vet          # go vet
make gosec        # 安全扫描
make cover-html   # 生成覆盖率报告

安全状态

  • 算法原语（sm2/sm3/sm4/sm9/zuc）委托 gmsm，继承其审计状态。
  • TLCP（tlcp）尚未通过独立第三方安全审计，标记 EXPERIMENTAL，不建议未经评估用于生产。
  • RFC 8998 栈（tls13gm/quicgm，Route C）已实现完整握手引擎与 QUIC packet protection，TLS 握手层已与 Tongsuo/BabaSSL 互通验证（见 互通矩阵）。Go / quic-go 上游尚不原生支持 RFC 8998，QUIC 层为 pollux-go 自有实现。
  • 密钥更新职责：pollux 仅提供 key update 原语（tls13gm.QUICKeyUpdate）， 不强制更新阈值——由传输层（quic-go）或直接集成方负责在阈值临近时发起更新， 避免长连接 SM4-GCM nonce 复用风险。

文档

License

MIT — 详情见 LICENSE。

Documentation

Overview

Package pollux provides Go integration tooling for Chinese national cryptographic (国密/GM) algorithms and protocols.

Pollux is a GM security integration toolkit — not a cryptography implementation. All core algorithms are provided by github.com/emmansun/gmsm; pollux adds:

  • Protocol integration (TLCP 1.1 handshake, HTTP helpers, QUIC-GM)
  • SM2-aware X.509 certificate handling (smx509)
  • Ergonomic Go-idiomatic APIs wrapping gmsm primitives
  • Secure memory operations for key material (internal/memsecure)

Sub-packages

  • sm2: SM2 digital signatures and key exchange (wraps gmsm/sm2)
  • sm3: SM3 hash function (wraps gmsm/sm3)
  • sm4: SM4 block cipher with GCM/CBC modes (wraps gmsm/sm4)
  • sm9: SM9 identity-based encryption (wraps gmsm/sm9)
  • zuc: ZUC stream cipher (wraps gmsm/zuc)
  • gmstd: GM/T standard helper functions
  • smx509: SM2-aware X.509 certificate creation, parsing, and verification
  • cert: High-level certificate management facade
  • tls: TLS cipher suite registry (national suite IDs only)
  • tls13: Standard TLS 1.3 configuration builders (Route A)
  • tlcp: TLCP 1.1 protocol (EXPERIMENTAL — pending security audit)
  • tls13gm: RFC 8998 TLS 1.3 GM cipher suites (interop-verified, Route C)
  • quicgm: RFC 9001 QUIC packet protection with SM4-GCM (Route C)
  • http: HTTP server/client helpers for TLS, TLCP, and hybrid

The primitive wrappers (sm2/sm3/sm4/sm9/zuc) delegate to gmsm and inherit its audit status. TLCP is EXPERIMENTAL pending independent security audit.

Source Files

View all Source files

Directories

Path Synopsis
Package aes provides convenience wrappers around the standard library crypto/aes, symmetric in API surface to github.com/iuboy/pollux-go/sm4.
 Package aes provides convenience wrappers around the standard library crypto/aes, symmetric in API surface to github.com/iuboy/pollux-go/sm4.
Package cert provides a unified certificate facade for both standard X.509 and SM2 (Chinese national cryptography) certificates.
 Package cert provides a unified certificate facade for both standard X.509 and SM2 (Chinese national cryptography) certificates.
Package gmstd provides helper functions per GM/T national cryptography standards.
 Package gmstd provides helper functions per GM/T national cryptography standards.
Package http provides net/http-compatible helpers for serving HTTP over standard TLS, TLCP (national, GB/T 38636-2020), TLS 1.3, or a hybrid mode that accepts both TLS and TLCP on the same port.
 Package http provides net/http-compatible helpers for serving HTTP over standard TLS, TLCP (national, GB/T 38636-2020), TLS 1.3, or a hybrid mode that accepts both TLS and TLCP on the same port.
internal
memsecure
Package memsecure provides secure memory operations for cryptographic material.
 Package memsecure provides secure memory operations for cryptographic material.
panicsafe
Package panicsafe converts unexpected panics into errors at public API boundaries.
 Package panicsafe converts unexpected panics into errors at public API boundaries.
Package jwt provides JWT signing methods for both the GM regime (SM2-SM3, asymmetric) and the international regime (HMAC-SHA-256/512, symmetric), plus a uniform Signer / Verifier abstraction so callers can switch algorithms by configuration without touching the call site.
 Package jwt provides JWT signing methods for both the GM regime (SM2-SM3, asymmetric) and the international regime (HMAC-SHA-256/512, symmetric), plus a uniform Signer / Verifier abstraction so callers can switch algorithms by configuration without touching the call site.
Package kdf provides hash-agnostic key- and password-derivation functions.
 Package kdf provides hash-agnostic key- and password-derivation functions.
Package pwHash provides PHC-format-encoded password hashing with a uniform PasswordHasher interface across the international (argon2id) and GM (pbkdf2-sm3) regimes.
 Package pwHash provides PHC-format-encoded password hashing with a uniform PasswordHasher interface across the international (argon2id) and GM (pbkdf2-sm3) regimes.
Package quic provides standard QUIC transport using TLS 1.3.
 Package quic provides standard QUIC transport using TLS 1.3.
Package quicgm provides QUIC over the RFC 8998 SM4-GCM cipher suite (TLS_SM4_GCM_SM3, 0x00C6), integrating the GM cryptographic primitives from the tls13gm package with the vendored quic-go fork.
 Package quicgm provides QUIC over the RFC 8998 SM4-GCM cipher suite (TLS_SM4_GCM_SM3, 0x00C6), integrating the GM cryptographic primitives from the tls13gm package with the vendored quic-go fork.
Package sha provides convenience wrappers around the standard library crypto/sha256 and crypto/sha512, symmetric in API surface to github.com/iuboy/pollux-go/sm3.
 Package sha provides convenience wrappers around the standard library crypto/sha256 and crypto/sha512, symmetric in API surface to github.com/iuboy/pollux-go/sm3.
Package sm2 implements the SM2 elliptic curve public key cryptography algorithm (GM/T 0003-2012), following crypto/ecdsa conventions.
 Package sm2 implements the SM2 elliptic curve public key cryptography algorithm (GM/T 0003-2012), following crypto/ecdsa conventions.
Package sm3 implements the SM3 cryptographic hash function (GM/T 0004-2012).
 Package sm3 implements the SM3 cryptographic hash function (GM/T 0004-2012).
Package sm4 implements the SM4 block cipher (GM/T 0002-2012).
 Package sm4 implements the SM4 block cipher (GM/T 0002-2012).
Package sm9 provides Go-idiomatic wrappers around gmsm/sm9.
 Package sm9 provides Go-idiomatic wrappers around gmsm/sm9.
Package smx509 provides SM2-aware X.509 certificate handling, extending crypto/x509 with national cryptography support.
 Package smx509 provides SM2-aware X.509 certificate handling, extending crypto/x509 with national cryptography support.
Package tlcp implements the Transport Layer Cryptography Protocol (TLCP), the Chinese national standard for transport-layer security (GB/T 38636-2020).
 Package tlcp implements the Transport Layer Cryptography Protocol (TLCP), the Chinese national standard for transport-layer security (GB/T 38636-2020).
Package tls provides a cipher suite ID registry for Chinese national cryptographic algorithms.
 Package tls provides a cipher suite ID registry for Chinese national cryptographic algorithms.
Package tls13 provides secure TLS 1.3 configuration builders for servers and clients.
 Package tls13 provides secure TLS 1.3 configuration builders for servers and clients.
Package tls13gm provides the RFC 8998 TLS 1.3 GM (国密) stack — the SM4-GCM, curveSM2, SM2, and SM3 cipher suite (TLS_SM4_GCM_SM3, 0x00C6) that the Go standard library crypto/tls does not support.
 Package tls13gm provides the RFC 8998 TLS 1.3 GM (国密) stack — the SM4-GCM, curveSM2, SM2, and SM3 cipher suite (TLS_SM4_GCM_SM3, 0x00C6) that the Go standard library crypto/tls does not support.
Package zuc provides Go-idiomatic wrappers around gmsm/zuc.
 Package zuc provides Go-idiomatic wrappers around gmsm/zuc.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.