pksigner

README

go-pksigner

Documentation

Index

• type Config
  • func (c Config) GetCertificateTemplate() []*pkcs11.Attribute
  • func (c Config) GetPrivateKeyTemplate() []*pkcs11.Attribute
  • func (c Config) SelectSlot(context *pkcs11.Ctx, slots []uint) (uint, error)
• type Store
  • func New(config Config) (*Store, error)
  • func (s Store) Close() error
  • func (s Store) Decrypt(rand io.Reader, msg []byte, opts crypto.DecrypterOpts) ([]byte, error)
  • func (s Store) LoadCertificate() (*piv.Certificate, error)
  • func (s Store) Login(pin string) error
  • func (s Store) Public() crypto.PublicKey
  • func (s Store) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)
  • func (s Store) TLSCertificate() (*tls.Certificate, error)

Types

type Config

type Config struct {
	// Full path to the PKCS#11 object on the filesystem. The exact value
	// of this depends on the host, but should usually end in a .so
	Module string

	// Label of the x.509 Certificate stored on the PKCS#11 token,
	// for PIV devices, one option for this might be
	// "Certificate for PIV Authentication"
	CertificateLabel string

	// Private key material backing the x.509 Certificate indicated by
	// CertificateLabel, one option for this might be "PIV AUTH key"
	PrivateKeyLabel string

	// Name of the token, if there are more than exactly one.
	TokenLabel string
}

Config is the HSM Configuration object, setting which PKCS#11 module to use, Certificate and Private Key strings, a PIN (if needed), and the label of the token.

func (Config) GetCertificateTemplate

func (c Config) GetCertificateTemplate() []*pkcs11.Attribute

GetCertificateTemplate creates a pkcs11.Attribute array containing constraints that should uniquely identify the PKCS#11 Certificate we're interested in

func (Config) GetPrivateKeyTemplate

func (c Config) GetPrivateKeyTemplate() []*pkcs11.Attribute

GetPrivateKeyTemplate returns a pkcs11.Attribute array containing constraints that should uniquely identify the PKCS#11 private key we're interested in

func (Config) SelectSlot

func (c Config) SelectSlot(context *pkcs11.Ctx, slots []uint) (uint, error)

SelectSlot takes a pkcs11.Ctx and a list of slots, figures out which slot is the slot we're interested in, returning an error if there's nothing we should be using.

type Store

type Store struct {
	PublicKey   crypto.PublicKey
	Certificate *piv.Certificate
	// contains filtered or unexported fields
}

Store is the internal hsm.Store encaupsulating state. This implements the store.Store interface, as well as crypto.Signer, and crypto.Decryptor.

func New

func New(config Config) (*Store, error)

New creates a new hsm.Store defined by the hsm.Config. If no slot can be found, or the underlying infrastructure throws a problem at us, we will return an error.

func (Store) Close

func (s Store) Close() error

Close logs out of the Token, and closes any open sessions we might have open. This method ought to be defer'd after creating a new hsm.Store.

func (Store) Decrypt

func (s Store) Decrypt(rand io.Reader, msg []byte, opts crypto.DecrypterOpts) ([]byte, error)

Decrypt implements crypto.Decryptor. This will have the HSM Decrypt the encrypted data given, ignoring `rand`, and using on chip entropy sources. This will return the data in cleartext.

func (Store) LoadCertificate

func (s Store) LoadCertificate() (*piv.Certificate, error)

LoadCertificate queries the underlying HSM Store for the x509 Certificate we're interested in, and returns a Go x509.Certificate.

func (Store) Login

func (s Store) Login(pin string) error

Login unlocks a smartcard with the provided PIN.

func (Store) Public

func (s Store) Public() crypto.PublicKey

Public returns the cached PublicKey, because the interface we're implementing doesn't want us to return errors, so, we'll force errors during startup.

This has a downside of not being able to read the PublicKey if it changes during our session (womp), but maybe that's not a problem? Who can know. If that's a problem you hit, maybe we should do something smarter here.

func (Store) Sign

func (s Store) Sign(rand io.Reader, digest []byte, opts crypto.SignerOpts) ([]byte, error)

Sign implements crypto.Signer. This will have the HSM sign the hash given, ignoring the entropy source `rand` on chip, and return the signature blob.

func (Store) TLSCertificate

func (s Store) TLSCertificate() (*tls.Certificate, error)

TLSCertificate queries the underlying HSM Store for the x509 Certificate we're interested in, and returns a tls.Certificate containing both the public and private portions.