crypto

Documentation

Index

• Constants
• type CryptoConfig
  • func (c CryptoConfig) Validate() error
• type CryptoProvider
  • func NewProvider(ctx context.Context, cfg CryptoConfig, c container.KeyContainer) (CryptoProvider, error)
• type GMProvider
  • func NewGMProvider(ctx context.Context, c container.KeyContainer) (*GMProvider, error)
  • func (p *GMProvider) Decrypt(ciphertext, key, iv []byte) ([]byte, error)
  • func (p *GMProvider) Encrypt(plain, key, iv []byte) ([]byte, error)
  • func (p *GMProvider) HMACKey() []byte
  • func (p *GMProvider) Hash(data []byte) ([]byte, error)
  • func (p *GMProvider) Info() GMProviderInfo
  • func (p *GMProvider) Mode() Mode
  • func (p *GMProvider) Sign(data []byte, privateKey stdcrypto.PrivateKey) ([]byte, error)
  • func (p *GMProvider) Verify(data, signature []byte, publicKey stdcrypto.PublicKey) (bool, error)
• type GMProviderInfo
• type LocalSeed
  • func GenerateLocalSeed(opts SeedOptions) (*LocalSeed, error)
  • func (s *LocalSeed) AsKVMap() map[string][]byte
• type Mode
• type RuntimeConfig
• type SeedOptions
• type TLSMaterials

Constants

const (
	AliasDefaultKeyCipherID   = "kms.local.defaultKeyCipher.id"
	AliasDefaultKeyCipher     = "kms.local.defaultKeyCipher"
	AliasDefaultAlias         = "kms.local.defaultAlias"
	AliasDefaultSm2PrivateKey = "kms.local.defaultSm2PrivateKey"
	AliasDefaultSm2PublicKey  = "kms.local.defaultSm2PublicKey"
	AliasDefaultDataKeyID     = "kms.local.defaultDataKeyId"
	AliasHMACKey              = "kms.local.hmacKey"
)

Alias names used when persisting a LocalSeed into a local_kv container. They mirror the property names produced by the legacy generate-kms-local-config.sh script so downstream consumers can keep the same key naming conventions.

Types

type CryptoConfig

type CryptoConfig struct {
	Mode          Mode
	AllowFallback bool
}

CryptoConfig controls crypto provider selection.

func (CryptoConfig) Validate

func (c CryptoConfig) Validate() error

Validate checks minimal provider config correctness.

type CryptoProvider

type CryptoProvider interface {
	Mode() Mode
	Hash(data []byte) ([]byte, error)
	Sign(data []byte, privateKey stdcrypto.PrivateKey) ([]byte, error)
	Verify(data []byte, signature []byte, publicKey stdcrypto.PublicKey) (bool, error)
	Encrypt(plain []byte, key []byte, iv []byte) ([]byte, error)
	Decrypt(ciphertext []byte, key []byte, iv []byte) ([]byte, error)
}

CryptoProvider is the unified crypto interface.

func NewProvider

func NewProvider(ctx context.Context, cfg CryptoConfig, c container.KeyContainer) (CryptoProvider, error)

NewProvider returns the CryptoProvider matching cfg.Mode, eagerly loading any required key material from the supplied KeyContainer.

The container is consulted only during construction; the returned provider caches all key material it needs in memory.

type GMProvider

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

GMProvider implements CryptoProvider with the tjfoc/gmsm stack:

• Hash : SM3
• Sign : SM2 (PKCS#8 DER private key, default UID baked in tjfoc)
• Verify : SM2 (X.509 DER public key)
• Encrypt : SM4-GCM
• Decrypt : SM4-GCM

Default keys are loaded from a KeyContainer at construction time and cached in memory for the lifetime of the provider; subsequent algorithm calls do not touch the container.

func NewGMProvider

func NewGMProvider(ctx context.Context, c container.KeyContainer) (*GMProvider, error)

NewGMProvider eagerly loads the default GM key set from the container and returns a ready-to-use provider. The container is only used during construction; the provider holds its own copies thereafter.

func (*GMProvider) Decrypt

func (p *GMProvider) Decrypt(ciphertext, key, iv []byte) ([]byte, error)

Decrypt SM4-GCM decrypts ciphertext. Mirrors Encrypt regarding key/iv:

• key : empty -> cached default SM4 key.
• iv : empty -> first NonceSize bytes of ciphertext are taken as iv.

func (*GMProvider) Encrypt

func (p *GMProvider) Encrypt(plain, key, iv []byte) ([]byte, error)

Encrypt SM4-GCM encrypts plain.

Behaviour:

• key : empty -> use cached default SM4 key; otherwise must be 16 bytes.
• iv : empty -> generate a random 12-byte nonce; the resulting output becomes nonce||ciphertext||tag so that the receiver can use Decrypt with iv=nil. When iv is provided it must be 12 bytes, and the output is the bare ciphertext||tag.

func (*GMProvider) HMACKey

func (p *GMProvider) HMACKey() []byte

HMACKey returns a defensive copy of the HMAC key cached from the container. The key itself is sensitive; callers must not log it.

func (*GMProvider) Hash

func (p *GMProvider) Hash(data []byte) ([]byte, error)

Hash returns SM3(data).

func (*GMProvider) Info

func (p *GMProvider) Info() GMProviderInfo

Info returns non-secret identifiers loaded from the container.

func (*GMProvider) Mode

func (p *GMProvider) Mode() Mode

Mode reports the active crypto stack.

func (*GMProvider) Sign

func (p *GMProvider) Sign(data []byte, privateKey stdcrypto.PrivateKey) ([]byte, error)

Sign computes an SM2 signature over data. When privateKey is nil the cached default private key is used; otherwise privateKey must be a *sm2.PrivateKey.

func (*GMProvider) Verify

func (p *GMProvider) Verify(data, signature []byte, publicKey stdcrypto.PublicKey) (bool, error)

Verify checks an SM2 signature over data. When publicKey is nil the cached default public key is used; otherwise publicKey must be a *sm2.PublicKey.

type GMProviderInfo

type GMProviderInfo struct {
	KeyID     string
	Alias     string
	DataKeyID string
}

GMProviderInfo exposes the non-secret identifiers loaded from the container, useful for logging/audit.

type LocalSeed

type LocalSeed struct {
	KeyID            string
	DefaultAlias     string
	DataKeyID        string
	SM2PrivatePKCS8  []byte
	SM2PublicX509    []byte
	DefaultCipherKey []byte
	HMACKey          []byte
}

LocalSeed bundles the random material a local_kv container needs to be bootstrapped with a fresh local-GM key set.

All byte slices are raw (not base64). Persist them as-is into the local_kv container; presentation/encoding is the consumer's choice.

func GenerateLocalSeed

func GenerateLocalSeed(opts SeedOptions) (*LocalSeed, error)

GenerateLocalSeed produces all key material required to seed a fresh local_kv container, mirroring the legacy generate-kms-local-config.sh script (SM2 keypair + SM4 default cipher + HMAC key + identifiers).

func (*LocalSeed) AsKVMap

func (s *LocalSeed) AsKVMap() map[string][]byte

AsKVMap returns alias -> raw bytes pairs ready to be written into a local_kv container. The returned map is independent of the receiver; callers may mutate it freely.

type Mode

type Mode string

Mode controls which crypto stack is active.

const (
	ModeLegacy Mode = "legacy"
	ModeGM     Mode = "gm"
	ModeHSM    Mode = "hsm"
)

type RuntimeConfig

type RuntimeConfig struct {
	Container container.ContainerConfig
	Provider  CryptoConfig
}

RuntimeConfig combines container and crypto selection in one place.

type SeedOptions

type SeedOptions struct {
	KeyID        string
	DefaultAlias string
	DataKeyID    string
}

SeedOptions controls deterministic identifiers in GenerateLocalSeed. Empty fields are populated with random or default values.

type TLSMaterials

type TLSMaterials struct {
	KeyPair tls.Certificate
	RootCAs *x509.CertPool
}

TLSMaterials carries minimal inputs for TLS setup.