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

Build Status

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

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    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.