keystore

Documentation

Overview

Package keystore provides a generic client and associated helpers for handling private keys that may be backed by an HSM.

Notes on testing

Testing the Keystore package predictably requires an HSM. Testcases are currently written for the "raw" KeyStore (no HSM), SoftHSMv2, YubiHSM2, and AWS CloudHSM. Only the "raw" tests run without any setup, but testing for SoftHSM is enabled by default in the Teleport docker buildbox and will be run in CI.

Testing this package with SoftHSMv2

To test with SoftHSMv2, you must install it (see https://github.com/opendnssec/SoftHSMv2 or https://packages.ubuntu.com/search?keywords=softhsm2) and set the "SOFTHSM2_PATH" environment variable to the location of SoftHSM2's PKCS11 library. Depending how you installed it, this is likely to be /usr/lib/softhsm/libsofthsm2.so or /usr/local/lib/softhsm/libsofthsm2.so.

The test will create its own config file and token, and clean up after itself.

Testing this package with YubiHSM2

To test with YubiHSM2, you must:

1. have a physical YubiHSM plugged in

2. install the SDK (https://developers.yubico.com/YubiHSM2/Releases/)

3. start the connector "yubihsm-connector -d"

4. create a config file connector = http://127.0.0.1:12345 debug

5. set "YUBIHSM_PKCS11_CONF" to the location of your config file

6. set "YUBIHSM_PKCS11_PATH" to the location of the PKCS11 library

The test will use the factory default pin of "0001password" in slot 0.

Testing this package with AWS CloudHSM

1. Create a CloudHSM Cluster and HSM, and activate them https://docs.aws.amazon.com/cloudhsm/latest/userguide/getting-started.html

2. Connect an EC2 instance to the cluster https://docs.aws.amazon.com/cloudhsm/latest/userguide/configure-sg-client-instance.html

3. Install the CloudHSM client on the EC2 instance https://docs.aws.amazon.com/cloudhsm/latest/userguide/install-and-configure-client-linux.html

4. Create a Crypto User (CU) https://docs.aws.amazon.com/cloudhsm/latest/userguide/manage-hsm-users.html

5. Set "CLOUDHSM_PIN" to "<username>:<password>" of your crypto user, eg "TestUser:hunter2"

6. Run the test on the connected EC2 instance

Testing Teleport with an HSM-backed CA

TBD as full support is added.

Index

• func KeyType(key []byte) types.PrivateKeyType
• type Config
  • func SetupSoftHSMTest(t *testing.T) Config
  • func (cfg *Config) CheckAndSetDefaults() error
• type HSMConfig
• type KeyStore
  • func NewHSMKeyStore(config *HSMConfig) (KeyStore, error)
  • func NewKeyStore(cfg Config) (KeyStore, error)
  • func NewRawKeyStore(config *RawConfig) KeyStore
• type RSAKeyPairSource
• type RawConfig

Functions

func KeyType

func KeyType(key []byte) types.PrivateKeyType

KeyType returns the type of the given private key.

Types

type Config

type Config struct {
	// RSAKeyPairSource is a function which returns raw keypairs to be used if
	// an hsm is not configured
	RSAKeyPairSource RSAKeyPairSource

	// Path is the path to the PKCS11 module.
	Path string
	// SlotNumber points to the PKCS11 slot to use, or nil if slot is unused.
	SlotNumber *int
	// TokenLabel is the label of the PKCS11 token to use.
	TokenLabel string
	// Pin is the PKCS11 pin for the given token.
	Pin string
	// HostUUID is the UUID of the local auth server this HSM is connected to.
	HostUUID string
}

Config is used to pass KeyStore configuration to NewKeyStore.

func SetupSoftHSMTest

func SetupSoftHSMTest(t *testing.T) Config

SetupSoftHSMToken is for use in tests only and creates a test SOFTHSM2 token. This should be used for all tests which need to use SoftHSM because the library can only be initialized once and SOFTHSM2_PATH and SOFTHSM2_CONF cannot be changed. New tokens added after the library has been initialized will not be found by the library.

A new token will be used for each `go test` invocation, but it's difficult to create a separate token for each test because because new tokens added after the library has been initialized will not be found by the library. It's also difficult to clean up the token because tests for all packages are run in parallel there is not a good time to safely delete the token or the entire token directory. Each test should clean up all keys that it creates because SoftHSM2 gets really slow when there are many keys for a given token.

func (*Config) CheckAndSetDefaults

func (cfg *Config) CheckAndSetDefaults() error

type HSMConfig

type HSMConfig struct {
	// Path is the path to the PKCS11 module.
	Path string
	// SlotNumber is the PKCS11 slot to use.
	SlotNumber *int
	// TokenLabel is the label of the PKCS11 token to use.
	TokenLabel string
	// Pin is the PKCS11 pin for the given token.
	Pin string

	// HostUUID is the UUID of the local auth server this HSM is connected to.
	HostUUID string
}

HSMConfig is used to pass HSM client configuration parameters.

type KeyStore

type KeyStore interface {
	// GenerateRSA creates a new RSA private key and returns its identifier and
	// a crypto.Signer. The returned identifier can be passed to GetSigner
	// later to get the same crypto.Signer.
	GenerateRSA() (keyID []byte, signer crypto.Signer, err error)

	// GetSigner returns a crypto.Signer for the given key identifier, if it is found.
	GetSigner(keyID []byte) (crypto.Signer, error)

	// GetTLSCertAndSigner selects the local TLS keypair from the CA ActiveKeys
	// and returns the PEM-encoded TLS cert and a crypto.Signer.
	GetTLSCertAndSigner(ca types.CertAuthority) ([]byte, crypto.Signer, error)

	// GetSSHSigner selects the local SSH keypair from the CA ActiveKeys and
	// returns an ssh.Signer.
	GetSSHSigner(ca types.CertAuthority) (ssh.Signer, error)

	// GetJWTSigner selects the local JWT keypair from the CA ActiveKeys and
	// returns a crypto.Signer.
	GetJWTSigner(ca types.CertAuthority) (crypto.Signer, error)

	// NewSSHKeyPair creates and returns a new SSHKeyPair.
	NewSSHKeyPair() (*types.SSHKeyPair, error)

	// NewTLSKeyPair creates and returns a new TLSKeyPair.
	NewTLSKeyPair(clusterName string) (*types.TLSKeyPair, error)

	// NewJWTKeyPair creates and returns a new JWTKeyPair.
	NewJWTKeyPair() (*types.JWTKeyPair, error)

	// HasLocalActiveKeys returns true if the given CA has any active keys that
	// are usable with this KeyStore.
	HasLocalActiveKeys(ca types.CertAuthority) bool

	// HasLocalAdditionalKeys returns true if the given CA has any additional
	// trusted keys that are usable with this KeyStore.
	HasLocalAdditionalKeys(ca types.CertAuthority) bool

	// DeleteKey deletes the given key from the KeyStore.
	DeleteKey(keyID []byte) error

	// DeleteUnusedKeys deletes all keys from the KeyStore if they are:
	// 1. Labeled by this KeyStore when they were created
	// 2. Not included in the argument usedKeys
	DeleteUnusedKeys(usedKeys [][]byte) error

	// GetAdditionalTrustedSSHSigner selects the local SSH keypair from the CA
	// AdditionalTrustedKeys and returns an ssh.Signer.
	GetAdditionalTrustedSSHSigner(ca types.CertAuthority) (ssh.Signer, error)

	// GetAdditionalTrustedTLSCertAndSigner selects the local TLS keypair from
	// the CA AdditionalTrustedKeys and returns the PEM-encoded TLS cert and a
	// crypto.Signer.
	GetAdditionalTrustedTLSCertAndSigner(ca types.CertAuthority) ([]byte, crypto.Signer, error)
}

KeyStore is an interface for creating and using cryptographic keys.

func NewHSMKeyStore

func NewHSMKeyStore(config *HSMConfig) (KeyStore, error)

func NewKeyStore

func NewKeyStore(cfg Config) (KeyStore, error)

NewKeyStore returns a new KeyStore

func NewRawKeyStore

func NewRawKeyStore(config *RawConfig) KeyStore

type RSAKeyPairSource

type RSAKeyPairSource func() (priv []byte, pub []byte, err error)

RSAKeyPairSource is a function type which returns new RSA keypairs.

type RawConfig

type RawConfig struct {
	RSAKeyPairSource RSAKeyPairSource
}