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
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
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
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
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
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.