Skip to content

Module github.com/bide-ai/bide/signer/pkcs11 ​

Go module github.com/bide-ai/bide/signer/pkcs11; all modules.

signer/pkcs11 ​

github.com/bide-ai/bide/signer/pkcs11 · pkg.go.dev · Stability: core

Package pkcs11 is an audit.Signer whose private key lives in a PKCS#11 token: a hardware security module, a smart card, or SoftHSM2 for tests.

Constants

  • const CKRDeviceRemoved = 0x00000032, const CKRKeyHandleInvalid = 0x00000060, const CKRPinIncorrect = 0x000000A0, const CKRPinExpired = 0x000000A3, const CKRPinLocked = 0x000000A4, const CKRSessionClosed = 0x000000B0, const CKRSessionHandleInvalid = 0x000000B3, const CKRTokenNotPresent = 0x000000E0, const CKRUserNotLoggedIn = 0x00000101: The CKR codes a caller is likely to act on (PKCS#11 v2.40 / v3.0 values).
  • const MinPINLength = 4: MinPINLength is the shortest PIN Open accepts, in characters.

Variables

  • var ErrNoEd25519: ErrNoEd25519 means the token cannot do Ed25519: it does not list CKM_EDDSA, or the key selected is not a CKK_EC_EDWARDS key.
  • var ErrNoP256: ErrNoP256 means Config.Scheme is audit.AlgECDSAP256 and the token does not list CKM_ECDSA, or the key selected is not an ECDSA P-256 key.
  • var ErrKeyNotFound: ErrKeyNotFound means no private key on the token matches the label and ID in Config.
  • var ErrAmbiguous: ErrAmbiguous means more than one token or key matches the Config; add a label, an ID or a slot so that exactly one does.
  • var ErrNoCgo: ErrNoCgo is returned by Open in a build without cgo, where no PKCS#11 library can be loaded.
  • var ErrExtractable: ErrExtractable means Config.RequireNonExtractable is set and the token does not mark the key CKA_EXTRACTABLE=false and CKA_SENSITIVE=true, or reports that it was once extractable or not sensitive (CKA_NEVER_EXTRACTABLE or CKA_ALWAYS_SENSITIVE false).
  • var ErrNoProtectedAuthPath: ErrNoProtectedAuthPath means Config.ProtectedAuthPath is set and the token does not have the CKF_PROTECTED_AUTHENTICATION_PATH flag: it has no PIN pad or reader of its own, so the PIN must be given (Config.PIN).

type CKRError ​

go
type CKRError struct {
	Code uint
}

CKRError is a PKCS#11 return code (CKR_*) the token or its library reported.

Methods

  • func (e CKRError) Error() string: Error names the code.

type Config ​

go
type Config struct {
	Module string

	TokenLabel string

	SlotID *uint

	Scheme audit.Alg

	KeyLabel string

	KeyID []byte

	PIN PINSource

	PublicKey []byte

	ProtectedAuthPath bool

	RequireNonExtractable bool
}

Config selects the token and the key.

type PINSource ​

go
type PINSource func() (string, error)

PINSource returns the user PIN of the token.

Constructors and functions

  • func PINFromEnv(name string) PINSource: PINFromEnv reads the PIN from the environment variable name.
  • func PINFromFile(path string) PINSource: PINFromFile reads the PIN from the file at path (a mounted secret, say), dropping one trailing line break.

type Signer ​

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

Signer signs with a key held by a PKCS#11 token (Ed25519 or ECDSA P-256, see Config.Scheme).

Constructors and functions

  • func Open(cfg Config) (*Signer, error): Open connects to the token, selects the key, and returns a Signer for it.

Methods

  • func (s *Signer) Alg() audit.Alg: Alg reports the signature scheme (Config.Scheme, audit.AlgEd25519 by default).
  • func (s *Signer) Close() error: Close ends the session and releases the module.
  • func (s *Signer) Format(f fmt.State, _ rune): Format writes String for every verb, so no fmt verb prints the configuration.
  • func (s *Signer) PublicKey() []byte: PublicKey returns the public key of the token's key (32 bytes for Ed25519, the 65-byte uncompressed point for P-256), in the encoding audit.NewVerifier reads.
  • func (s *Signer) Sign(message []byte) ([]byte, error): Sign returns the token's signature over message.
  • func (s *Signer) String() string: String describes the signer by its key identity (audit.KeyID of the public key), which is not secret.

signer/pkcs11/pkcs11test ​

github.com/bide-ai/bide/signer/pkcs11/pkcs11test · pkg.go.dev · Stability: core

Package pkcs11test gives tests a SoftHSM2 token to sign with, so code that uses the signer package can be tested against a real PKCS#11 library with no hardware.

Functions

  • func Run(m *testing.M, provision func(*Token) error) int: Run is for TestMain: it creates a SoftHSM2 token in a scratch directory, calls provision with it so the test binary can put its keys on the token, runs the tests, and removes the directory.

type Token ​

go
type Token struct {
	Module string

	Label string

	PIN string
}

Token is the SoftHSM2 token a test process shares.

Constructors and functions

  • func Require(t testing.TB) *Token: Require returns the shared token, or skips the test (fails it, with BIDE_REQUIRE_SOFTHSM set) when SoftHSM2 is unavailable or the token could not be provisioned.

Methods

  • func (k *Token) GenerateEd25519(label string, id []byte) error: GenerateEd25519 creates an Ed25519 key pair on the token with the label and CKA_ID.
  • func (k *Token) GenerateEd25519AlwaysAuth(label string, id []byte) error: GenerateEd25519AlwaysAuth creates an Ed25519 key pair whose private key has CKA_ALWAYS_AUTHENTICATE true: each signature needs a context-specific login between C_SignInit and C_Sign.
  • func (k *Token) GenerateEd25519Extractable(label string, id []byte) error: GenerateEd25519Extractable creates an Ed25519 key pair whose private key is extractable and not sensitive, a key Config.RequireNonExtractable must refuse.
  • func (k *Token) GenerateEd25519NoSign(label string, id []byte) error: GenerateEd25519NoSign creates an Ed25519 key pair whose private key may not sign (CKA_SIGN false), a key the signer must refuse.
  • func (k *Token) GenerateEd25519Remarked(label string, id []byte) error: GenerateEd25519Remarked creates an Ed25519 key pair that is extractable and not sensitive, then marks the private key CKA_EXTRACTABLE=false and CKA_SENSITIVE=true, the only direction a token allows.
  • func (k *Token) GenerateP256(label string) error: GenerateP256 creates an ECDSA P-256 key pair on the token, a key the signer must refuse.
  • func (k *Token) GenerateP256Extractable(label string, id []byte) error: GenerateP256Extractable creates an ECDSA P-256 key pair whose private key is extractable and not sensitive, a key Config.RequireNonExtractable must refuse.
  • func (k *Token) GenerateP256Key(label string, id []byte) error: GenerateP256Key creates an ECDSA P-256 key pair with the label and CKA_ID whose private key is sensitive and not extractable, the key an approver or a signer should keep on a token.

Apache-2.0 licensed.