sm2

Documentation

Overview

Package sm2 implements the SM2 elliptic curve public key cryptography algorithm (GM/T 0003-2012), following crypto/ecdsa conventions.

SM2 provides digital signatures and key exchange on the SM2 elliptic curve. PrivateKey implements the crypto.Signer interface.

Basic usage:

key, err := sm2.GenerateKey(rand.Reader)
sig, err := sm2.SignASN1(rand.Reader, key, digest, nil)
ok := sm2.VerifyASN1(&key.PublicKey, digest, sig)

Status: wrapper around gmsm/sm2

Index

• func CompressPublicKey(pub *ecdsa.PublicKey) []byte
• func DecompressPublicKey(data []byte) (*ecdsa.PublicKey, error)
• func Decrypt(priv *PrivateKey, ciphertext []byte) ([]byte, error)
• func EncryptASN1(random io.Reader, pub *ecdsa.PublicKey, msg []byte) ([]byte, error)
• func EnvelopeDecrypt(priv *PrivateKey, env *EnvelopeResult) ([]byte, error)
• func EnvelopeDecryptSM4(priv *PrivateKey, encryptedKey, nonce, ciphertext []byte) ([]byte, error)
• func EnvelopeEncryptSM4(pub *ecdsa.PublicKey, plaintext []byte) (encryptedKey, nonce, ciphertext []byte, err error)
• func Equal(x, y *ecdsa.PublicKey) bool
• func MarshalPKCS8PrivateKey(key *PrivateKey) ([]byte, error)
• func MarshalUncompressed(pub *ecdsa.PublicKey) []byte
• func NewPublicKey(der []byte) (*ecdsa.PublicKey, error)
• func NewSM2SignerOption(forceGMSign bool, uid []byte) crypto.SignerOpts
• func P256() elliptic.Curve
• func ParsePublicKeyFromPEM(pemData []byte) (*ecdsa.PublicKey, error)
• func SM2SignerOption(uid []byte) crypto.SignerOpts
• func SignASN1(r io.Reader, priv *PrivateKey, hash []byte, opts crypto.SignerOpts) ([]byte, error)
• func SignWithSM2(r io.Reader, priv *PrivateKey, uid, data []byte) ([]byte, error)
• func UnmarshalUncompressed(data []byte) (*ecdsa.PublicKey, error)
• func VerifyASN1(pub *PublicKey, hash, sig []byte) bool
• func VerifyWithSM2(pub *ecdsa.PublicKey, uid, data, sig []byte) bool
• func WritePrivateKeyToPEM(key *PrivateKey) ([]byte, error)
• func WritePublicKeyToPEM(key *ecdsa.PublicKey) ([]byte, error)
• type EnvelopeResult
  • func EnvelopeEncrypt(pub *ecdsa.PublicKey, plaintext []byte) (*EnvelopeResult, error)
• type PrivateKey
  • func BytesToPrivateKey(data []byte) (*PrivateKey, error)
  • func GenerateKey(r io.Reader) (*PrivateKey, error)
  • func GenerateKeyDefault() (*PrivateKey, error)
  • func NewPrivateKey(der []byte) (*PrivateKey, error)
  • func ParsePrivateKeyFromPEM(pemData []byte) (*PrivateKey, error)
• type PublicKey
• type SecureKeyBytes
  • func PrivateKeyToBytesSecure(key *PrivateKey) (*SecureKeyBytes, error)
  • func (s *SecureKeyBytes) Data() []byte
  • func (s *SecureKeyBytes) Destroy()

Functions

func CompressPublicKey

func CompressPublicKey(pub *ecdsa.PublicKey) []byte

CompressPublicKey compresses SM2 public key to 33 bytes (02/03 prefix + X coordinate).

func DecompressPublicKey

func DecompressPublicKey(data []byte) (*ecdsa.PublicKey, error)

DecompressPublicKey decompresses compressed SM2 public key (33 bytes) to full public key.

func Decrypt

func Decrypt(priv *PrivateKey, ciphertext []byte) ([]byte, error)

Decrypt decrypts SM2-encrypted data.

func EncryptASN1

func EncryptASN1(random io.Reader, pub *ecdsa.PublicKey, msg []byte) ([]byte, error)

EncryptASN1 encrypts data with an SM2 public key, returning ASN.1 format.

func EnvelopeDecrypt

func EnvelopeDecrypt(priv *PrivateKey, env *EnvelopeResult) ([]byte, error)

EnvelopeDecrypt decrypts digital envelope using SM2 private key.

func EnvelopeDecryptSM4

func EnvelopeDecryptSM4(priv *PrivateKey, encryptedKey, nonce, ciphertext []byte) ([]byte, error)

EnvelopeDecryptSM4 decrypts SM2+SM4-GCM digital envelope (simplified).

SECURITY NOTE: Error messages are intentionally generic ("sm2: decryption failed") to prevent timing side-channel leakage. An attacker who can measure decryption time should not be able to distinguish between "SM2 decryption failed" and "SM4-GCM authentication failed" errors.

func EnvelopeEncryptSM4

func EnvelopeEncryptSM4(pub *ecdsa.PublicKey, plaintext []byte) (encryptedKey, nonce, ciphertext []byte, err error)

EnvelopeEncryptSM4 encrypts using SM2+SM4-GCM digital envelope (simplified, non-PKCS#7 format). Returns SM2-encrypted SM4 key, GCM nonce, SM4-GCM ciphertext.

func Equal

func Equal(x, y *ecdsa.PublicKey) bool

Equal reports whether two SM2 public keys are equal.

func MarshalPKCS8PrivateKey

func MarshalPKCS8PrivateKey(key *PrivateKey) ([]byte, error)

MarshalPKCS8PrivateKey 将 SM2 私钥序列化为 PKCS#8 DER（含 SM2 OID）。 经 gmsm/smx509 派发——直接调 stdlib x509.MarshalPKCS8PrivateKey 不会写入 SM2 OID，反序列化时会被识别为普通 ECDSA。与 WritePrivateKeyToPEM 共用底层， 供需要原始 DER（非 PEM）的调用方使用。

func MarshalUncompressed

func MarshalUncompressed(pub *ecdsa.PublicKey) []byte

MarshalUncompressed serializes SM2 public key to uncompressed format (65 bytes: 04 + X + Y).

func NewPublicKey

func NewPublicKey(der []byte) (*ecdsa.PublicKey, error)

NewPublicKey parses a DER-encoded SM2 public key.

func NewSM2SignerOption

func NewSM2SignerOption(forceGMSign bool, uid []byte) crypto.SignerOpts

NewSM2SignerOption returns a signer option for SM2 signing. forceGMSign true uses the national standard SM2 signing mode.

func P256

func P256() elliptic.Curve

P256 returns the SM2 elliptic curve.

func ParsePublicKeyFromPEM

func ParsePublicKeyFromPEM(pemData []byte) (*ecdsa.PublicKey, error)

ParsePublicKeyFromPEM 解析 PEM 编码的 SM2 公钥。

func SM2SignerOption

func SM2SignerOption(uid []byte) crypto.SignerOpts

SM2SignerOption returns crypto.SignerOpts for SM2 signing with a user ID.

Deprecated: use NewSM2SignerOption(true, uid) instead for explicit control over the forceGMSign parameter.

func SignASN1

func SignASN1(r io.Reader, priv *PrivateKey, hash []byte, opts crypto.SignerOpts) ([]byte, error)

SignASN1 signs a hash using SM2 and returns the signature in ASN.1 format. opts may be nil for default behavior, or SM2SignerOption(uid) for GM/T 0009.

func SignWithSM2

func SignWithSM2(r io.Reader, priv *PrivateKey, uid, data []byte) ([]byte, error)

SignWithSM2 signs data with SM2 using the specified user ID per GM/T 0009-2012.

func UnmarshalUncompressed

func UnmarshalUncompressed(data []byte) (*ecdsa.PublicKey, error)

UnmarshalUncompressed parses SM2 public key from uncompressed format.

func VerifyASN1

func VerifyASN1(pub *PublicKey, hash, sig []byte) bool

VerifyASN1 verifies an ASN.1-encoded SM2 signature.

func VerifyWithSM2

func VerifyWithSM2(pub *ecdsa.PublicKey, uid, data, sig []byte) bool

VerifyWithSM2 verifies an SM2 signature with the specified user ID.

func WritePrivateKeyToPEM

func WritePrivateKeyToPEM(key *PrivateKey) ([]byte, error)

WritePrivateKeyToPEM 将 SM2 私钥序列化为 PEM 格式 (PKCS#8)。

func WritePublicKeyToPEM

func WritePublicKeyToPEM(key *ecdsa.PublicKey) ([]byte, error)

WritePublicKeyToPEM 将 SM2 公钥序列化为 PEM 格式。

Types

type EnvelopeResult

type EnvelopeResult struct {
	// DER-encoded PKCS#7 EnvelopedData (contains SM2-encrypted SM4 key + SM4 ciphertext).
	EnvelopedData []byte
	// contains filtered or unexported fields
}

EnvelopeResult represents a digital envelope encryption result.

func EnvelopeEncrypt

func EnvelopeEncrypt(pub *ecdsa.PublicKey, plaintext []byte) (*EnvelopeResult, error)

EnvelopeEncrypt encrypts plaintext using SM2 public key digital envelope. Internal process: generate random SM4 key -> SM4-CBC encrypt plaintext -> SM2 encrypt SM4 key -> assemble PKCS#7 EnvelopedData.

type PrivateKey

type PrivateKey = gmsmSM2.PrivateKey

PrivateKey is an SM2 private key. It implements crypto.Signer.

Note: this is a type alias (=) to gmsmSM2.PrivateKey, which provides direct access to all underlying methods. If the underlying library changes in a future major version, this alias will be replaced by a wrapper struct.

func BytesToPrivateKey

func BytesToPrivateKey(data []byte) (*PrivateKey, error)

BytesToPrivateKey recovers SM2 private key from 32-byte big-endian integer.

func GenerateKey

func GenerateKey(r io.Reader) (*PrivateKey, error)

GenerateKey generates a new SM2 private key.

func GenerateKeyDefault

func GenerateKeyDefault() (*PrivateKey, error)

GenerateKeyDefault generates a new SM2 private key using crypto/rand.Reader.

func NewPrivateKey

func NewPrivateKey(der []byte) (*PrivateKey, error)

NewPrivateKey parses a DER-encoded SM2 private key.

func ParsePrivateKeyFromPEM

func ParsePrivateKeyFromPEM(pemData []byte) (*PrivateKey, error)

ParsePrivateKeyFromPEM 解析 PEM 编码的 SM2 私钥。 支持 PKCS#8 和 EC PRIVATE KEY 格式。

type PublicKey

type PublicKey = ecdsa.PublicKey

PublicKey is an SM2 public key.

Note: this is a type alias (=) to ecdsa.PublicKey. See PrivateKey docs for implications.

type SecureKeyBytes

type SecureKeyBytes struct {
	// contains filtered or unexported fields
}

SecureKeyBytes holds sensitive private key bytes with an explicit Destroy method. This provides a safer alternative to PrivateKeyToBytes by making cleanup part of the type contract.

func PrivateKeyToBytesSecure

func PrivateKeyToBytesSecure(key *PrivateKey) (*SecureKeyBytes, error)

PrivateKeyToBytesSecure returns the private key scalar as a fixed-length 32-byte big-endian SecureKeyBytes that must be explicitly destroyed after use. This is the recommended way to access raw private key bytes.

The 32-byte fixed-length encoding matches the contract of NewPrivateKey and BytesToPrivateKey, so the output round-trips cleanly through both. (A minimal big.Int encoding — key.D.Bytes() — could be shorter when the scalar has leading zero bytes, which those parsers reject.)

Example:

skb, err := sm2.PrivateKeyToBytesSecure(key)
if err != nil { ... }
defer skb.Destroy()
use(skb.Data())

func (*SecureKeyBytes) Data

func (s *SecureKeyBytes) Data() []byte

Data returns the underlying key bytes. Callers must not retain references after calling Destroy.

func (*SecureKeyBytes) Destroy

func (s *SecureKeyBytes) Destroy()

Destroy securely zeroes the key material and releases the reference.