gmsm

GMSM is a high-performance Go library for Chinese National Standard (ShangMi) cryptography and Post-Quantum Cryptography (PQC).

Supported Algorithms:

• ShangMi (Guomi): SM2 (Elliptic Curve), SM3 (Hash), SM4 (Block Cipher), SM9 (Identity-Based), ZUC (Stream Cipher).
• Post-Quantum (PQC): ML-KEM (FIPS 203), ML-DSA (FIPS 204), SLH-DSA (FIPS 205).

Key Features:

• High Performance: SIMD/Assembly optimizations for amd64, arm64, loong64, ppc64le, s390x, and riscv64.
• Standard Compliance: Supports PKCS ecosystem, CFCA interoperability, and NIST PQC standards.
• Security: Constant-time implementations for critical paths and purego fallback paths.

The sm9 package provides implementations for the SM9 identity-based cryptographic algorithm. The currently supported operations include:

• Keys generation (密钥生成)
• Sign/Verify (数字签名算法)
• Key Exchange (密钥交换协议)
• Wrap/Unwrap Key (密钥封装机制)
• Encryption/Decryption (公钥加密算法)

The pkcs8 package provides functionality to process private keys in PKCS#8 format (as defined in RFC5208 and RFC5958), filling gaps in the Go standard crypto/x509 package.

Specifically, it addresses these limitations in the standard library:

1. Encryption Support: Unlike crypto/x509.ParsePKCS8PrivateKey, which only handles unencrypted PKCS#8 keys, this package can handle both unencrypted PrivateKeyInfo and encrypted EncryptedPrivateKeyInfo formats using PKCS#5 (v2.0) algorithms.
2. Conversion: It provides functions to convert RSA/ECDSA (and ShangMi) private keys into PKCS#8 format, which the standard library lacks.
3. ShangMi Support: This implementation includes support for ShangMi algorithms.

Use this package when you need to securely work with encrypted private keys on disk or when you need to export existing keys into the PKCS#8 format.

GMSM is a high-performance Go cryptography library designed for ShangMi algorithms and modern post-quantum primitives. It features SIMD/assembly optimizations for multiple architectures including amd64, arm64, loong64, ppc64le, s390x, and riscv64.

Supported Algorithms

• ShangMi: SM2, SM3, SM4, SM9, ZUC
• Post-Quantum (NIST PQC FIPS 203/204/205): ML-KEM, ML-DSA, SLH-DSA

PKI and Interoperability

• Standards: PKCS ecosystem (PKCS#7, PKCS#8, PKCS#12), CFCA support, and smx509.
• Core Building Blocks: Block modes, padding, DRBG, randomness, ECDH/SM2MQV, and TLS 1.3 hybrid key exchange.

The performance of rand.Read() is influenced by three main factors:

1. First Call: Requires entropy collection and DRBG initialization (including KAT self-tests), typically taking ~4-5ms.
2. Subsequent Calls: Directly generates from the DRBG, with a small overhead to fetch 16 bytes of additional OS input.
3. Re-seeding: When the security level interval is reached, the system must re-collect triple entropy (OS, CPU jitter, and Hash loop), taking ~4-5ms.

Note: For performance-sensitive applications that do not require GM/T 0105-2021 compliance, consider using Go's standard crypto/rand directly.

ZUC (GM/T 0001-2012) is a stream cipher algorithm supporting amd64, arm64, and ppc64x architectures via SIMD, AES, and carry-less multiplication instructions.

Supported Algorithms:

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

SM2 and ECDSA are NOT compatible. Even though both are elliptic curve algorithms, they differ in several critical ways:

• Signature Algorithms: SM2 incorporates a Z value.
• Curves: SM2 uses sm2p256v1, whereas ECDSA typically uses secp256r1.
• Hash Algorithms: SM2 uses SM3, while ECDSA typically uses SHA-256.

Attempting to use SM2 keys with ECDSA will result in invalid signatures.

The mlkem package provides an implementation of the Module-Lattice-Based Key-Encapsulation Mechanism as specified in NIST FIPS 203. It offers three parameter sets corresponding to different security levels:

• mlkem512: Level 1 security (approximately AES-128). Key size: 800 bytes; Ciphertext size: 768 bytes.
• mlkem768: Level 3 security (approximately AES-192). Key size: 1184 bytes; Ciphertext size: 1088 bytes.
• mlkem1024: Level 5 security (approximately AES-256). Key size: 1568 bytes; Ciphertext size: 1568 bytes.

The implementation is optimized for performance using SIMD assembly on supported architectures, while providing a pure-Go fallback.

SM2 ciphertext can be concatenated in different orders:

• C1C2C3: Legacy format (2010 standard).
• C1C3C2: Current format (2012+ standard).

The GMSM library automatically detects the format during decryption. For new implementations, it is recommended to use C1C3C2 or ASN.1 format.

SM3 (GM/T 0004-2012) is a cryptographic hash algorithm featuring SIMD optimizations:

• amd64: Optimizes message expansion for AVX2+BMI2 and SSE2+SSSE3.
• arm64: Uses NEON instructions and A64 extended cryptographic instructions.
• s390x/ppc64x: Optimizes message expansion through vector instructions.

ML-DSA operates on polynomials in the ring $\mathbb{Z}_q[x]/(x^{256}+1)$ where $q = 8,380,417$. The implementation focuses on several critical hot paths:

• NTT (Number Theoretic Transform): A 7-layer butterfly network used to convert polynomials between coefficient and NTT domains ($O(n \log n)$).
• Point-wise multiplication: Performed in the NTT domain using nttMul and nttMulAcc.
• Decompose / Hint: Uses HighBits, LowBits, MakeHint, and UseHint for the signature scheme's rejection sampling.
• Encoding/Decoding: Employs variable-width bit-packing for signature components (e.g., $z$ uses 18/20-bit, $w_1$ uses 4/6-bit, and hints).