GMSM: High-Performance Go ShangMi and Post-Quantum Crypto Library

!GitHub go.mod Go version (branch)

English | 简体中文

GMSM is a production-ready Go cryptography library focused on ShangMi algorithms (SM2/SM3/SM4/SM9/ZUC) and modern post-quantum primitives (ML-KEM/ML-DSA/SLH-DSA), designed to balance secure defaults, practical APIs, and cross-architecture performance.

Why GMSM

• Broad standards coverage: ShangMi standards, PKCS ecosystem, and NIST PQC (FIPS 203/204/205).
• Practical API design: Interfaces aligned with Go standard library patterns for easier adoption.
• High performance across CPUs: SIMD/assembly optimizations for amd64, arm64, loong64, ppc64le, s390x, riscv64, and more.
• Security with portability: Pure Go fallbacks plus constant-time implementations on sensitive paths.
• Operational confidence: Multi-architecture CI, coverage tracking, and active maintenance.

Quick Start

go get github.com/emmansun/gmsm@latest

package main
import (
  "fmt"
"github.com/emmansun/gmsm/sm3"
)
func main() {
  sum := sm3.Sum([]byte("hello gmsm"))
  fmt.Printf("SM3: %x\n", sum)
}

Capability Snapshot

• ShangMi: SM2, SM3, SM4, SM9, ZUC
• Post-Quantum: ML-KEM, ML-DSA, SLH-DSA
• PKI and interoperability: smx509, PKCS#7, PKCS#8, CFCA support
• Core building blocks: block modes, padding, DRBG, randomness, ECDH/SM2MQV, and TLS 1.3 hybrid key exchange

User Documentation

• Project Wiki
• SM2 Elliptic Curve Public Key Cryptography Algorithm Application Guide
• SM3 Cryptographic Hash Algorithm Application Guide
• SM4 Block Cipher Algorithm Application Guide
• SM9 Identity-Based Cryptography Algorithm Application Guide
• ZUC Stream Cipher Algorithm Application Guide
• CFCA Interoperability Guide
• PKCS#7 Application Guide
• PKCS#12 Application Guide
• Deterministic Random Number Generator (DRBG) and Software Random Number Generator Application Guide
• PQC

Core Modules

Public Key Cryptography Algorithms

SM2 - Elliptic Curve Public Key Cryptography Algorithm

Features:

• Digital Signature Algorithm (GB/T 32918.2-2016)
• Public Key Encryption Algorithm (GB/T 32918.4-2016)
• Key Exchange Protocol (GB/T 32918.3-2016)
• Key Pair Protection Data Format (GB/T 35276-2017)

SM9 - Identity-Based Cryptography Algorithm

Features:

• Key Generation Algorithm (GM/T 0044-2016)
• Digital Signature Algorithm
• Key Encapsulation Mechanism (KEM)
• Public Key Encryption Algorithm
• Key Exchange Protocol

Symmetric Cryptography Algorithms

SM3 - Cryptographic Hash Algorithm

Architecture Optimizations:

• amd64: Optimizes message expansion for AVX2+BMI2 and SSE2+SSSE3 instruction sets
• arm64: Uses NEON instructions to optimize message expansion and provides implementation based on A64 extended cryptographic instructions
• s390x/ppc64x: Optimizes message expansion through vector instructions
• riscv64: Uses Zvksh instructions

SM4 - Block Cipher Algorithm

Architecture Optimizations:

• amd64: Uses GFNI, AES-NI instructions combined with AVX2/SSE2+SSSE3
• arm64: Uses AES instructions combined with NEON and provides implementation based on A64 extended cryptographic instructions
• ppc64x: Uses vsbox instructions combined with vector instructions
• riscv64: Uses Zvksed instructions, GCM uses Zvkg or Zvbc instructions

• ECB (Electronic Codebook)
• CBC (Cipher Block Chaining)
• GCM (Galois/Counter Mode)
• GCM-SIV (RFC 8452)
• XTS (XEX-based tweaked-codebook mode, supports GB/T 17964-2021 and NIST SP 800-38E)

ZUC - Zu Chongzhi Stream Cipher Algorithm

Features:

• Confidentiality Algorithm (128-EEA3 / 256-EEA3)
• Integrity Algorithm (128-EIA3 / 256-EIA3)

Message Authentication Codes

CBCMAC - Block Cipher Based Message Authentication Code

Supported MAC Modes:

• CBC-MAC (Scheme 1)
• EMAC (Scheme 2)
• ANSI Retail MAC (Scheme 3)
• MAC-DES (Scheme 4)
• CMAC (Scheme 5, RFC 4493)
• LMAC (Scheme 6)
• TR-CBC-MAC (Scheme 7)
• CBCR-MAC (Scheme 8)

Operation Modes and Padding

CIPHER - Block Cipher Operation Modes

Supported Operation Modes:

• ECB: Electronic Codebook mode
• CCM: Counter with CBC-MAC mode (RFC 3610)
• XTS: XEX-based tweaked-codebook mode (GB/T 17964-2021 / NIST SP 800-38E)
• HCTR: Hash-Counter mode (newly added in GB/T 17964-2021)
• BC: Block Chaining mode (GB/T 17964 legacy mode)
• OFBNLF: Output Feedback mode with Non-Linear Function (GB/T 17964 legacy mode)

• XTS mode implements the cipher.BlockMode interface and contains internal tweak state, does NOT support concurrent use
• BC mode has similar functionality to CBC mode
• OFBNLF mode has limited room for performance optimization from a software implementation perspective

PADDING - Padding Schemes

| Padding Scheme | Corresponding Standard | |---------------|------------------------| | PKCS#7 | GB/T 17964-2021 Appendix C.2 Padding Method 1 / RFC 5652 | | ISO/IEC 9797-1 Method 2 | GB/T 17964-2021 Appendix C.3 Padding Method 2 | | ANSI X.923 | ANSI X9.23 Standard | | ISO/IEC 9797-1 Method 3 | GB/T 17964-2021 Appendix C.4 Padding Method 3 | | Zero Padding | Non-standard (legacy compatibility) |

Secure Implementation:

• All schemes provide both ConstantTimeUnpad() and Unpad() methods
• Encrypted data MUST use ConstantTimeUnpad() to defend against timing attacks
• Unpad() is only for performance optimization with non-sensitive data

PKI and Certificates

SMX509 - Chinese Commercial Cryptography Certificate Extension

PKCS#7 - Cryptographic Message Syntax

PKCS#8 - Private-Key Information Syntax

Key Agreement and Random Numbers

ECDH - Elliptic Curve Diffie-Hellman

Supported Protocols:

• ECDH Key Agreement
• SM2MQV Key Agreement (recommended)

• No big.Int dependency for better performance
• Can serve as an alternative implementation to the sm2 package key exchange protocol

DRBG - Deterministic Random Bit Generator

Features:

• Validated with NIST official test vectors
• Does NOT support concurrent use

CFCA Interoperability

CFCA - China Financial Certification Authority Extension

Features:

• SM2 private key and certificate encapsulation (PKCS#12_SM2 format)
• Envelope encryption and digital signature
• CSR generation and parsing
• Private key decryption

Post-Quantum Cryptography

MLKEM - Module-Lattice-Based Key-Encapsulation Mechanism

Supported Parameter Sets:

• ML-KEM-512
• ML-KEM-768
• ML-KEM-1024

• amd64: NTT, inverse NTT, and polynomial multiplication are vectorized using AVX2 instructions
• arm64: NTT, inverse NTT, and polynomial multiplication are vectorized using NEON instructions
• riscv64: NTT, inverse NTT, and polynomial multiplication are vectorized using RVV instructions
• loong64: NTT, inverse NTT, and polynomial multiplication are vectorized using LASX instructions
• ppc64le: NTT, inverse NTT, and polynomial multiplication are vectorized using VSX / VMX (AltiVec) instructions

MLDSA - Module-Lattice-Based Digital Signature

Architecture Optimizations:

• amd64: NTT, inverse NTT, and polynomial multiplication are vectorized using AVX2 instructions
• arm64: NTT, inverse NTT, and polynomial multiplication are vectorized using NEON instructions
• riscv64: NTT, inverse NTT, and polynomial multiplication are vectorized using RVV instructions
• loong64: NTT, inverse NTT, and polynomial multiplication are vectorized using LASX instructions

SLHDSA - Stateless Hash-Based Digital Signature

Developer Testing

This project ships a differential testing framework (internal/cryptotest/diff) for its multi-architecture assembly optimizations: direct kernel paths and the public dispatch paths are compared bit-exactly against trusted reference implementations over explicitly declared input domains, enforced by CI (including Intel SDE and a QEMU riscv64 VLEN matrix) plus scheduled fuzzing. See the Differential Testing Framework guide.

Related Projects

• Trisia/TLCP - A Go language implementation of "GB/T 38636-2020 Information Security Technology - Transport Layer Cryptography Protocol".
• Trisia/Randomness - A Go language implementation of randomness testing specifications.
• PKCS12 - A fork of SSLMate/go-pkcs12 with commercial cryptography support. Due to the older PKCS12 standard and lower security, it is maintained as a separate project.
• MKSMCERT - A tool for generating SM2 private keys and certificates, mainly for development and testing. It is a fork of FiloSottile/mkcert with commercial cryptography support.
• JavaScript Implementations

License

Acknowledgements

The SM4 block cipher algorithm amd64 SIMD AES-NI implementation (SSE part) algorithm is derived from mjosaarinen/sm4ni.

The initial version of SM9/BN256 code was copied from the cloudflare/bn256 project, and later the basic prime field, extension field, elliptic curve operations, etc. were rewritten.

The Zu Chongzhi stream cipher algorithm implementation amd64 SIMD AES-NI, CLMUL implementation algorithm is derived from the Intel(R) Multi-Buffer Crypto for IPsec Library project.

The PKCS7 package code is a fork of the mozilla-services/pkcs7 project (which was archived on February 10, 2024) with commercial cryptography extensions.

The PKCS8 package code is a fork of the youmark/pkcs8 project with commercial cryptography extensions.

Disclaimer

Before using this project, please be sure to carefully read the GMSM Software Disclaimer!

Support and Follow

Star History