pkcs11key: github.com/letsencrypt/pkcs11key/v4 Index | Files

package pkcs11key

import "github.com/letsencrypt/pkcs11key/v4"

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.

Index

Package Files

config.go key.go pool.go

type Config Uses

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

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

type Key Uses

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 Uses

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 Uses

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 Uses

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

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

func (*Key) Sign Uses

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 Uses

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 Uses

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 Uses

func (p *Pool) Destroy() error

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

func (*Pool) Public Uses

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 Uses

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.

Package pkcs11key imports 11 packages (graph) and is imported by 13 packages. Updated 2020-01-22. Refresh now. Tools for package owners.