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"
- 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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func KeyType ¶
func KeyType(key []byte) types.PrivateKeyType
KeyType returns the type of the given private key.
Types ¶
type Config ¶
type Config struct { // Software holds configuration parameters specific to software KeyStores Software SoftwareConfig // PKCS11 hold configuration parameters specific to PKCS11 KeyStores. PKCS11 PKCS11Config }
Config is used to pass KeyStore configuration to NewKeyStore.
func SetupSoftHSMTest ¶
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 ¶
type KeyStore ¶
type KeyStore interface { // 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 // 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) // contains filtered or unexported methods }
KeyStore is an interface for creating and using cryptographic keys.
func NewKeyStore ¶
NewKeyStore returns a new KeyStore
func NewPKCS11KeyStore ¶
func NewPKCS11KeyStore(config *PKCS11Config) (KeyStore, error)
func NewSoftwareKeyStore ¶
func NewSoftwareKeyStore(config *SoftwareConfig) KeyStore
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 RSAKeyPairSource ¶
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