keystore

package
v11.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 13, 2022 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Overview

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

Notes on testing

Fully testing the Keystore package predictably requires an HSM. Testcases are currently written for the software KeyStore (no HSM), SoftHSMv2, YubiHSM2, AWS CloudHSM, and GCP KMS. Only the software 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"

  1. 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 this package with GCP CloudHSM

1. Sign into the Gcloud CLI

  1. Create a keyring ``` gcloud kms keyrings create "test" --location global ```

  2. Set GCP_KMS_KEYRING to the name of the keyring you just created ``` gcloud kms keyrings list --location global export GCP_KMS_KEYRING=<name from above> ```

4. Run the unit tests

Testing Teleport with an HSM-backed CA

Integration tests can be found in integration/hsm. They run with SoftHSM by default, manually alter the auth config as necessary to test different HSMs.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

type Config struct {
	// Software holds configuration parameters specific to software keystores.
	Software SoftwareConfig
	// PKCS11 holds configuration parameters specific to PKCS#11 keystores.
	PKCS11 PKCS11Config
	// GCPKMS holds configuration parameters specific to GCP KMS keystores.
	GCPKMS GCPKMSConfig
	// Logger is a logger to be used by the keystore.
	Logger logrus.FieldLogger
}

Config holds configuration parameters for the keystore. A software keystore will be the default if no other is configured. Only one inner config other than Softare should be set. It is okay to always set the Software config even when a different keystore is desired because it will only be used if all others are empty.

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 GCPKMSConfig 

type GCPKMSConfig struct {
	// KeyRing is the fully qualified name of the GCP KMS keyring.
	KeyRing string
	// ProtectionLevel specifies how cryptographic operations are performed.
	// For more information, see https://cloud.google.com/kms/docs/algorithms#protection_levels
	// Supported options are "HSM" and "SOFTWARE".
	ProtectionLevel string
	// HostUUID is the UUID of the teleport host (auth server) running this
	// keystore. Used to label keys so that they can be queried and deleted per
	// server without races when multiple auth servers are configured with the
	// same KeyRing.
	HostUUID string
	// contains filtered or unexported fields
}

GCPKMS holds configuration parameters specific to GCP KMS keystores.

func (*GCPKMSConfig) CheckAndSetDefaults 

func (cfg *GCPKMSConfig) CheckAndSetDefaults() error

type Manager 

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

Manager provides an interface to interact with teleport CA private keys, which may be software keys or held in an HSM or other key manager.

func NewManager 

func NewManager(ctx context.Context, cfg Config) (*Manager, error)

NewManager returns a new keystore Manager

func (*Manager) GetAdditionalTrustedSSHSigner 

func (m *Manager) GetAdditionalTrustedSSHSigner(ctx context.Context, ca types.CertAuthority) (ssh.Signer, error)

GetSSHSigner selects a usable SSH keypair from the given CA AdditionalTrustedKeys and returns an ssh.Signer.

func (*Manager) GetAdditionalTrustedTLSCertAndSigner 

func (m *Manager) GetAdditionalTrustedTLSCertAndSigner(ctx context.Context, ca types.CertAuthority) ([]byte, crypto.Signer, error)

GetAdditionalTrustedTLSCertAndSigner selects a usable TLS keypair from the given CA and returns the PEM-encoded TLS certificate and a crypto.Signer.

func (*Manager) GetJWTSigner 

func (m *Manager) GetJWTSigner(ctx context.Context, ca types.CertAuthority) (crypto.Signer, error)

GetJWTSigner selects a usable JWT keypair from the given keySet and returns a crypto.Signer.

func (*Manager) GetSSHSigner 

func (m *Manager) GetSSHSigner(ctx context.Context, ca types.CertAuthority) (ssh.Signer, error)

GetSSHSigner selects a usable SSH keypair from the given CA ActiveKeys and returns an ssh.Signer.

func (*Manager) GetTLSCertAndSigner 

func (m *Manager) GetTLSCertAndSigner(ctx context.Context, ca types.CertAuthority) ([]byte, crypto.Signer, error)

GetTLSCertAndSigner selects a usable TLS keypair from the given CA and returns the PEM-encoded TLS certificate and a crypto.Signer.

func (*Manager) HasUsableActiveKeys 

func (m *Manager) HasUsableActiveKeys(ctx context.Context, ca types.CertAuthority) (bool, error)

HasUsableActiveKeys returns true if the given CA has any usable active keys.

func (*Manager) HasUsableAdditionalKeys 

func (m *Manager) HasUsableAdditionalKeys(ctx context.Context, ca types.CertAuthority) (bool, error)

HasUsableActiveKeys returns true if the given CA has any usable additional trusted keys.

func (*Manager) NewJWTKeyPair 

func (m *Manager) NewJWTKeyPair(ctx context.Context) (*types.JWTKeyPair, error)

New JWTKeyPair create a new JWT keypair in the keystore backend and returns it.

func (*Manager) NewSSHKeyPair 

func (m *Manager) NewSSHKeyPair(ctx context.Context) (*types.SSHKeyPair, error)

NewSSHKeyPair generates a new SSH keypair in the keystore backend and returns it.

func (*Manager) NewTLSKeyPair 

func (m *Manager) NewTLSKeyPair(ctx context.Context, clusterName string) (*types.TLSKeyPair, error)

NewTLSKeyPair creates a new TLS keypair in the keystore backend and returns it.

type PKCS11Config 

type PKCS11Config 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
}

PKCS11Config is used to pass PKCS11 HSM client configuration parameters.

func (*PKCS11Config) CheckAndSetDefaults 

func (cfg *PKCS11Config) CheckAndSetDefaults() error

type RSAKeyOption 

type RSAKeyOption func(*RSAKeyOptions)

RSAKeyOption is a functional option for RSA key generation.

func WithDigestAlgorithm 

func WithDigestAlgorithm(alg crypto.Hash) RSAKeyOption

type RSAKeyOptions 

type RSAKeyOptions struct {
	DigestAlgorithm crypto.Hash
}

RSAKeyOptions configure options for RSA key generation.

type RSAKeyPairSource 

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

RSAKeyPairSource is a function type which returns new RSA keypairs.

type SoftwareConfig 

type SoftwareConfig struct {
	RSAKeyPairSource RSAKeyPairSource
}

func (*SoftwareConfig) CheckAndSetDefaults 

func (cfg *SoftwareConfig) CheckAndSetDefaults() error

Source Files

View all Source files

Directories

Path Synopsis
internal
faketime

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.