pkcs11key

README

PKCS11Key

The pkcs11key package implements a crypto.Signer interface for a PKCS#11 private key.

If you are using Go modules, you should import this with the module-compatible path github.com/letsencrypt/pkcs11key/v4

License summary

Some of this code is Copyright (c) 2014 CloudFlare Inc., some is Copyright (c) 2015 Internet Security Research Group.

The code is licensed under the BSD 2-clause license. See the LICENSE file for more details.

Documentation

Overview

Package pkcs11key implements crypto.Signer for PKCS #11 private keys. See https://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.pdf for details of the Cryptoki PKCS#11 API. See https://github.com/letsencrypt/pkcs11key/blob/master/test.sh for examples of how to test and/or benchmark. Latest version of this package is v4: import "github.com/letsencrypt/pkcs11key/v4"

Index

• type Config
• type Key
  • func New(modulePath, tokenLabel, pin string, publicKey crypto.PublicKey) (*Key, error)
  • func (ps *Key) Destroy() error
  • func (ps *Key) Public() crypto.PublicKey
  • func (ps *Key) Sign(rand io.Reader, msg []byte, opts crypto.SignerOpts) (signature []byte, err error)
• type Pool
  • func NewPool(n int, modulePath, tokenLabel, pin string, publicKey crypto.PublicKey) (*Pool, error)
  • func (p *Pool) Destroy() error
  • func (p *Pool) Public() crypto.PublicKey
  • func (p *Pool) Sign(rand io.Reader, msg []byte, opts crypto.SignerOpts) ([]byte, error)

Types

type Config

type Config struct {
	Module        string
	TokenLabel    string
	PIN           string
	PublicKeyPath string
}

Config contains configuration information required to use a PKCS #11 key.

type Key

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

Key is an implementation of the crypto.Signer interface using a key stored in a PKCS#11 hardware token. This enables the use of PKCS#11 tokens with the Go x509 library's methods for signing certificates.

Each Key represents one session. Its session handle is protected internally by a mutex, so at most one Sign operation can be active at a time. For best performance you may want to instantiate multiple Keys using pkcs11key.Pool. Each one will have its own session and can be used concurrently. Note that some smartcards like the Yubikey Neo do not support multiple simultaneous sessions and will error out on creation of the second Key object.

Note: If you instantiate multiple Keys without using Pool, it is *highly* recommended that you create all your Key objects serially, on your main thread, checking for errors each time, and then farm them out for use by different goroutines. If you fail to do this, your application may attempt to login repeatedly with an incorrect PIN, locking the PKCS#11 token.

func New

func New(modulePath, tokenLabel, pin string, publicKey crypto.PublicKey) (*Key, error)

New instantiates a new handle to a PKCS #11-backed key.

func (*Key) Destroy

func (ps *Key) Destroy() error

Destroy tears down a Key by closing the session. It should be called before the key gets GC'ed, to avoid leaving dangling sessions.

func (*Key) Public

func (ps *Key) Public() crypto.PublicKey

Public returns the public key for the PKCS #11 key.

func (*Key) Sign

func (ps *Key) Sign(rand io.Reader, msg []byte, opts crypto.SignerOpts) (signature []byte, err error)

Sign performs a signature using the PKCS #11 key.

type Pool

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

Pool is a pool of Keys suitable for high performance parallel work. Key on its own is suitable for multi-threaded use because it has built-in locking, but one Key can have at most one operation inflight at a time. If you are using an HSM that supports multiple sessions, you may want to use a Pool instead, which contains multiple signers. Pool satisfies the Signer interface just as Key does, and farms out work to multiple sessions under the hood. This assumes you are calling Sign from multiple goroutines (as would be common in an RPC or HTTP environment). If you only call Sign from a single goroutine, you will only ever get single-session performance.

func NewPool

func NewPool(n int, modulePath, tokenLabel, pin string, publicKey crypto.PublicKey) (*Pool, error)

NewPool creates a pool of Keys of size n.

func (*Pool) Destroy

func (p *Pool) Destroy() error

Destroy calls destroy for each of the member keys, shutting down their sessions.

func (*Pool) Public

func (p *Pool) Public() crypto.PublicKey

Public returns the public key of any one of the signers in the pool. Since they were all created with the same arguments, the public key should be the same for each one.

func (*Pool) Sign

func (p *Pool) Sign(rand io.Reader, msg []byte, opts crypto.SignerOpts) ([]byte, error)

Sign performs a signature using an available PKCS #11 key. If there is no key available, it blocks until there is.