keystore

package
v0.0.0-...-5c79d48 Latest Latest
Warning

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

 Go to latest Published: Feb 15, 2024 License: AGPL-3.0 Imports: 48 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 AWSKMSConfig 

type AWSKMSConfig struct {
	Cluster    string
	AWSAccount string
	AWSRegion  string

	CloudClients CloudClientProvider
	// contains filtered or unexported fields
}

AWSKMSConfig holds configuration parameters specific to AWS KMS keystores.

func (*AWSKMSConfig) CheckAndSetDefaults 

func (c *AWSKMSConfig) CheckAndSetDefaults() error

CheckAndSetDefaults checks that required parameters of the config are properly set and sets defaults.

type CloudClientProvider 

type CloudClientProvider interface {
	// GetAWSSTSClient returns AWS STS client for the specified region.
	GetAWSSTSClient(ctx context.Context, region string, opts ...cloud.AWSAssumeRoleOptionFn) (stsiface.STSAPI, error)
	// GetAWSKMSClient returns AWS KMS client for the specified region.
	GetAWSKMSClient(ctx context.Context, region string, opts ...cloud.AWSAssumeRoleOptionFn) (kmsiface.KMSAPI, error)
}

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
	// AWSKMS holds configuration parameter specific to AWS KMS keystores.
	AWSKMS AWSKMSConfig
	// 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 Software 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 HSMTestConfig 

func HSMTestConfig(t *testing.T) Config

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) DeleteUnusedKeys 

func (m *Manager) DeleteUnusedKeys(ctx context.Context, activeKeys [][]byte) error

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) (*UsableKeysResult, 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) (*UsableKeysResult, 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

type UsableKeysResult 

type UsableKeysResult struct {
	// CAHasPreferredKeyType is true if the CA contains any key matching the key
	// type the keystore is currently configured to use when generating new
	// keys.
	CAHasPreferredKeyType bool
	// CAHasUsableKeys is true if the CA contains any key that the keystore as
	// currently configured can use for signatures.
	CAHasUsableKeys bool
	// PreferredKeyType is a description of the key type the keystore is
	// currently configured to use when generating new keys.
	PreferredKeyType string
	// CAKeyTypes is a list of descriptions of all the keys types currently
	// stored in the CA. It is only guaranteed to be valid if
	// CAHasPreferredKeyType is false.
	CAKeyTypes []string
}

UsableKeysResult holds the result of a call to HasUsableActiveKeys or HasUsableAdditionalTrustedKeys.

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.