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

package pkcs11key

import "github.com/letsencrypt/pkcs11key"

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

Package Files

config.go doc.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.

This function will find the private key to sign with by finding a copy of the provided public key in the token, then looking for a private key object that has the same CKA_ID as that public key. From https://docs.oasis-open.org/pkcs11/pkcs11-base/v2.40/pkcs11-base-v2.40.pdf:

"The CKA_ID field is intended to distinguish among multiple keys. In

the case of public and private keys, this field assists in handling
multiple keys held by the same subject; the key identifier for a
public key and its corresponding private key should be the same."

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.

Directories

PathSynopsis
v4Package pkcs11key implements crypto.Signer for PKCS #11 private keys.

Package pkcs11key imports 11 packages (graph) and is imported by 67 packages. Updated 2019-12-09. Refresh now. Tools for package owners.