pkcs11

Documentation

Overview

Package pkcs11 implements a signing key backed by a PKCS#11 token or HSM. The private key never leaves the token: signing is performed on-device via the PKCS#11 C_Sign operation. Ed25519 (CKM_EDDSA) is the only key algorithm today; see algo.go for the per-algorithm seam.

Index

• type Config
• type Signer
  • func Open(cfg Config) (s *Signer, err error)
  • func (s *Signer) Close() error
  • func (s *Signer) PubKey() []byte
  • func (s *Signer) Scheme() config.Algorithm
  • func (s *Signer) Sign(_ context.Context, signBytes []byte) ([]byte, error)

Types

type Config

type Config struct {
	Module     string
	TokenLabel string
	Slot       *uint
	KeyLabel   string
	KeyID      []byte
	PIN        string
	PINEnv     string
	PINFile    string
	Algorithm  config.Algorithm
}

Config describes how to open a key on a PKCS#11 token. Exactly one of TokenLabel/Slot selects the token, at least one of KeyLabel/KeyID selects the key, and exactly one of PIN/PINEnv/PINFile supplies the user PIN. Algorithm defaults to "ed25519" when empty.

type Signer

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

Signer signs on a PKCS#11 token. It owns a single long-lived session; the mutex serializes signing (PKCS#11 sessions are not safe for concurrent use) and guards Close.

func Open

func Open(cfg Config) (s *Signer, err error)

Open loads the PKCS#11 module, logs into the selected token, locates the key, and caches its public key. Any failure is returned (fatal at startup for the chain). On success the returned Signer holds an open, logged-in session that must be released with Close.

func (*Signer) Close

func (s *Signer) Close() error

Close logs out, closes the session, and tears down the module. It is idempotent.

func (*Signer) PubKey

func (s *Signer) PubKey() []byte

PubKey returns the public key cached at Open.

func (*Signer) Scheme

func (s *Signer) Scheme() config.Algorithm

Scheme returns the config.Algorithm.

func (*Signer) Sign

func (s *Signer) Sign(_ context.Context, signBytes []byte) ([]byte, error)

Sign signs the canonical consensus sign-bytes on the token.