Documentation

Overview

Package keys defines the interface to and implementation of key management operations.

Although exported, this package is non intended for general consumption. It is a shared dependency between multiple exposure notifications projects. We cannot guarantee that there won't be breaking changes in the future.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ParseECDSAPublicKey

func ParseECDSAPublicKey(pemBlock string) (*ecdsa.PublicKey, error)

ParseECDSAPublicKey is a convenience function for decoding an ECDSA public key in PEM format.

func TestEncryptionKey

func TestEncryptionKey(tb testing.TB, kms KeyManager) string

TestEncryptionKey creates a new encryption key and key version in the given key manager. If the provided key manager does not support managing encryption keys, it calls t.Fatal.

func TestSigningKey

func TestSigningKey(tb testing.TB, kms KeyManager) string

TestSigningKey creates a new signing key and key version in the given key manager. If the provided key manager does not support managing signing keys, it calls t.Fatal.

Types

type AWSKMS

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

AWSKMS implements the keys.KeyManager interface and can be used to sign export files using AWS KMS.

func (*AWSKMS) Decrypt

func (s *AWSKMS) Decrypt(ctx context.Context, keyID string, ciphertext []byte, aad []byte) ([]byte, error)

func (*AWSKMS) Encrypt

func (s *AWSKMS) Encrypt(ctx context.Context, keyID string, plaintext []byte, aad []byte) ([]byte, error)

func (*AWSKMS) NewSigner

func (s *AWSKMS) NewSigner(ctx context.Context, keyID string) (crypto.Signer, error)

type AZKeyID

type AZKeyID struct {
	Vault   string
	Key     string
	Version string
}

func ParseAZKeyID

func ParseAZKeyID(keyID string) (*AZKeyID, error)

type AzureKeyVault

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

AzureKeyVault implements the keys.KeyManager interface and can be used to sign export files.

func (*AzureKeyVault) CreateKeyVersion

func (v *AzureKeyVault) CreateKeyVersion(ctx context.Context, parent string) (string, error)

CreateKeyVersion creates a new key version for the given parent, returning the ID of the new version. The parent key must already exist.

func (*AzureKeyVault) CreateSigningKey

func (v *AzureKeyVault) CreateSigningKey(ctx context.Context, parent, name string) (string, error)

CreateSigningKey creates a new signing key in the given parent, returning the id. If the key already exists, it returns the key's id.

func (*AzureKeyVault) Decrypt

func (v *AzureKeyVault) Decrypt(ctx context.Context, keyID string, ciphertext []byte, aad []byte) ([]byte, error)

func (*AzureKeyVault) DestroyKeyVersion

func (v *AzureKeyVault) DestroyKeyVersion(ctx context.Context, id string) error

DestroyKeyVersion destroys the given key version, if it exists. If the version does not exist, it should not return an error.

func (*AzureKeyVault) Encrypt

func (v *AzureKeyVault) Encrypt(ctx context.Context, keyID string, plaintext []byte, aad []byte) ([]byte, error)

func (*AzureKeyVault) NewSigner

func (v *AzureKeyVault) NewSigner(ctx context.Context, keyID string) (crypto.Signer, error)

NewSigner creates a new signer that uses a key in HashiCorp Vault's transit backend. The keyID in the format:

AZURE_KEY_VAULT_NAME/SECRET_NAME/SECRET_VERSION

For example:

my-company-vault/api-key/1

Both name and version are required.

func (*AzureKeyVault) SigningKeyVersions

func (v *AzureKeyVault) SigningKeyVersions(ctx context.Context, parent string) ([]SigningKeyVersion, error)

SigningKeyVersions returns the list of signing keys for the provided parent. If the parent does not exist, it returns an error.

type AzureKeyVaultSigner

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

func NewAzureKeyVaultSigner

func NewAzureKeyVaultSigner(ctx context.Context, client *keyvault.BaseClient, vault, key, version string) (*AzureKeyVaultSigner, error)

NewAzureKeyVaultSigner creates a new signing interface compatible with HashiCorp Vault's transit backend. The key name and key version are required.

func (*AzureKeyVaultSigner) Public

func (s *AzureKeyVaultSigner) Public() crypto.PublicKey

Public returns the public key. The public key is fetched when the signer is created.

func (*AzureKeyVaultSigner) Sign

func (s *AzureKeyVaultSigner) Sign(_ io.Reader, digest []byte, _ crypto.SignerOpts) ([]byte, error)

Sign signs the given digest using the public key.

type CloudKMSSigningKeyVersion

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

func (*CloudKMSSigningKeyVersion) CreatedAt

func (k *CloudKMSSigningKeyVersion) CreatedAt() time.Time

func (*CloudKMSSigningKeyVersion) DestroyedAt

func (k *CloudKMSSigningKeyVersion) DestroyedAt() time.Time

func (*CloudKMSSigningKeyVersion) KeyID

func (k *CloudKMSSigningKeyVersion) KeyID() string

func (*CloudKMSSigningKeyVersion) Signer

type Config

type Config struct {
	KeyManagerType KeyManagerType `env:"KEY_MANAGER, default=GOOGLE_CLOUD_KMS"`

	// CreateHSMKeys indicates than when keys are creating, HSM level
	// protection should or should not be used if available.
	// Adherence to this config setting is optional and based
	// upon the key manager implementation and underlying capabilities.
	CreateHSMKeys bool `env:"CREATE_HSM_KEYS, default=true"`

	// FilesystemRoot is the root path where keys are managed on the filesystem.
	FilesystemRoot string `env:"KEY_FILESYSTEM_ROOT"`
}

Config defines configuration.

type EncryptionKeyManager

type EncryptionKeyManager interface {
	// CreateEncryptionKey creates a new encryption key in the given parent,
	// returning the id. If the key already exists, it returns the key's id.
	CreateEncryptionKey(ctx context.Context, parent, name string) (string, error)

	KeyVersionCreator
	KeyVersionDestroyer
}

EncryptionKeyManager supports extended management of encryption keys, versions, and rotation.

type Filesystem

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

Filesystem is a key manager that uses the filesystem to store and retrieve keys. It should only be used for local development and testing.

func NewFilesystem

func NewFilesystem(ctx context.Context, root string) (*Filesystem, error)

NewFilesystem creates a new KeyManager backed by the local filesystem. It should only be used for development and testing.

If root is provided and does not exist, it will be created. If root is a relative path, it's relative to where the process is currently executing. If root is not supplied, all data is dumped in the current working directory.

In general, root should either be a hardcoded path like $(pwd)/local or a temporary directory like os.TempDir().

func (*Filesystem) CreateEncryptionKey

func (k *Filesystem) CreateEncryptionKey(_ context.Context, parent, name string) (string, error)

CreateEncryptionKey creates an encryption key. For this implementation, that means it creates a folder on disk (but no keys inside). If the folder already exists, it returns its name.

func (*Filesystem) CreateKeyVersion

func (k *Filesystem) CreateKeyVersion(_ context.Context, parent string) (string, error)

CreateKeyVersion creates a new key version for the parent. If the parent is a signing key, it creates a signing key. If the parent is an encryption key, it creates an encryption key. If the parent does not exist, it returns an error.

func (*Filesystem) CreateSigningKey

func (k *Filesystem) CreateSigningKey(_ context.Context, parent, name string) (string, error)

CreateSigningKey creates a signing key. For this implementation, that means it creates a folder on disk (but no keys inside). If the folder already exists, it returns its name.

func (*Filesystem) Decrypt

func (k *Filesystem) Decrypt(ctx context.Context, keyID string, ciphertext []byte, aad []byte) ([]byte, error)

Decrypt decrypts the ciphertext. It returns an error if decryption fails or if the key does not exist.

func (*Filesystem) DestroyKeyVersion

func (k *Filesystem) DestroyKeyVersion(_ context.Context, id string) error

DestroyKeyVersion destroys the given key version. It does nothing if the key does not exist.

func (*Filesystem) Encrypt

func (k *Filesystem) Encrypt(ctx context.Context, keyID string, plaintext []byte, aad []byte) ([]byte, error)

Encrypt encrypts the given plaintext and aad with the key. If the key does not exist, it returns an error.

func (*Filesystem) NewSigner

func (k *Filesystem) NewSigner(ctx context.Context, keyID string) (crypto.Signer, error)

NewSigner creates a new signer from the given key. If the key does not exist, it returns an error. If the key is not a signing key, it returns an error.

func (*Filesystem) SigningKeyVersions

func (k *Filesystem) SigningKeyVersions(ctx context.Context, parent string) ([]SigningKeyVersion, error)

SigningKeyVersions lists all the versions for the given parent. If the provided parent is not a signing key, it returns an error.

type GoogleCloudKMS

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

GoogleCloudKMS implements the keys.KeyManager interface and can be used to sign export files.

func (*GoogleCloudKMS) CreateKeyVersion

func (kms *GoogleCloudKMS) CreateKeyVersion(ctx context.Context, parent string) (string, error)

CreateKeyVersion creates a new version for the given key. The parent key must already exist.

func (*GoogleCloudKMS) CreateSigningKey

func (kms *GoogleCloudKMS) CreateSigningKey(ctx context.Context, parent, name string) (string, error)

CreateSigningKey creates a new signing key in Cloud KMS. If a key already exists, it returns the existing key.

func (*GoogleCloudKMS) Decrypt

func (kms *GoogleCloudKMS) Decrypt(ctx context.Context, keyID string, ciphertext []byte, aad []byte) ([]byte, error)

func (*GoogleCloudKMS) DestroyKeyVersion

func (kms *GoogleCloudKMS) DestroyKeyVersion(ctx context.Context, id string) error

DestroyKeyVersion marks the given key version for destruction. If the version does not exist, it does nothing. The id is the full resource name like projects/locations/keyRings/...

func (*GoogleCloudKMS) Encrypt

func (kms *GoogleCloudKMS) Encrypt(ctx context.Context, keyID string, plaintext []byte, aad []byte) ([]byte, error)

func (*GoogleCloudKMS) NewSigner

func (kms *GoogleCloudKMS) NewSigner(ctx context.Context, keyID string) (crypto.Signer, error)

func (*GoogleCloudKMS) SigningKeyVersions

func (kms *GoogleCloudKMS) SigningKeyVersions(ctx context.Context, parent string) ([]SigningKeyVersion, error)

SigningKeyVersions returns the list of key versions for the parent parsed as signing keys.

type HCValueKeyID

type HCValueKeyID struct {
	Name    string
	Version string
}

func NewHCValueKeyID

func NewHCValueKeyID(keyID string) (*HCValueKeyID, error)

type HashiCorpVault

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

HashiCorpVault implements the keys.KeyManager interface and can be used to sign export files and encrypt/decrypt data.

For encryption keys, when using value, the keys must be created with

`derived=true`

func (*HashiCorpVault) CreateKeyVersion

func (v *HashiCorpVault) CreateKeyVersion(ctx context.Context, parent string) (string, error)

CreateKeyVersion rotates the given key.

func (*HashiCorpVault) CreateSigningKey

func (v *HashiCorpVault) CreateSigningKey(ctx context.Context, parent, name string) (string, error)

CreateSigningKey creates a new signing key with the given name.

func (*HashiCorpVault) Decrypt

func (v *HashiCorpVault) Decrypt(ctx context.Context, keyID string, ciphertext []byte, aad []byte) ([]byte, error)

func (*HashiCorpVault) DestroyKeyVersion

func (v *HashiCorpVault) DestroyKeyVersion(ctx context.Context, id string) error

DestroyKeyVersion is unimplemented on Vault. Vault can only trim keys up to a point (which might be unsafe).

func (*HashiCorpVault) Encrypt

func (v *HashiCorpVault) Encrypt(ctx context.Context, keyID string, plaintext []byte, aad []byte) ([]byte, error)

func (*HashiCorpVault) NewSigner

func (v *HashiCorpVault) NewSigner(ctx context.Context, keyID string) (crypto.Signer, error)

NewSigner creates a new signer that uses a key in HashiCorp Vault's transit backend. The keyID is in the format:

name@version

Both name and version are required.

func (*HashiCorpVault) SigningKeyVersions

func (v *HashiCorpVault) SigningKeyVersions(ctx context.Context, parent string) ([]SigningKeyVersion, error)

SigningKeyVersions returns the signing keys for the given key name.

type HashiCorpVaultSigner

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

func NewHashiCorpVaultSigner

func NewHashiCorpVaultSigner(ctx context.Context, client *vaultapi.Client, name, version string) (*HashiCorpVaultSigner, error)

NewHashiCorpVaultSigner creates a new signing interface compatible with HashiCorp Vault's transit backend. The key name and key version are required.

func (*HashiCorpVaultSigner) Public

Public returns the public key. The public key is fetched when the signer is created.

func (*HashiCorpVaultSigner) Sign

func (s *HashiCorpVaultSigner) Sign(_ io.Reader, digest []byte, _ crypto.SignerOpts) ([]byte, error)

Sign signs the given digest using the public key.

type KeyManager

type KeyManager interface {
	NewSigner(ctx context.Context, keyID string) (crypto.Signer, error)

	// Encrypt will encrypt a byte array along with accompanying Additional Authenticated Data (AAD).
	// The ability for AAD to be empty, depends on the implementation being used.
	//
	// Currently Google Cloud KMS, Hashicorp Vault and AWS KMS support AAD
	// The Azure Key Vault implementation does not.
	Encrypt(ctx context.Context, keyID string, plaintext []byte, aad []byte) ([]byte, error)

	// Decrypt will decrypt a previously encrypted byte array along with accompanying Additional
	// Authenticated Data (AAD).
	// If AAD was passed in on the encryption, the same AAD must be passed in to decrypt.
	//
	// Currently Google Cloud KMS, Hashicorp Vault and AWS KMS support AAD
	// The Azure Key Vault implementation does not.
	Decrypt(ctx context.Context, keyID string, ciphertext []byte, aad []byte) ([]byte, error)
}

KeyManager defines the interface for working with a KMS system that is able to sign bytes using PKI. KeyManager implementations must be able to return a crypto.Signer.

func KeyManagerFor

func KeyManagerFor(ctx context.Context, config *Config) (KeyManager, error)

KeyManagerFor returns the appropriate key manager for the given type.

func NewAWSKMS

func NewAWSKMS(ctx context.Context) (KeyManager, error)

func NewAzureKeyVault

func NewAzureKeyVault(ctx context.Context) (KeyManager, error)

NewAzureKeyVault creates a new KeyVault key manager instance.

func NewGoogleCloudKMS

func NewGoogleCloudKMS(ctx context.Context, config *Config) (KeyManager, error)

func NewHashiCorpVault

func NewHashiCorpVault(ctx context.Context) (KeyManager, error)

NewHashiCorpVault creates a new Vault key manager instance.

func TestKeyManager

func TestKeyManager(tb testing.TB) KeyManager

TestKeyManager creates a new key manager suitable for use in tests.

type KeyManagerType

type KeyManagerType string

KeyManagerType defines a specific key manager.

const (
	KeyManagerTypeAWSKMS         KeyManagerType = "AWS_KMS"
	KeyManagerTypeAzureKeyVault  KeyManagerType = "AZURE_KEY_VAULT"
	KeyManagerTypeGoogleCloudKMS KeyManagerType = "GOOGLE_CLOUD_KMS"
	KeyManagerTypeHashiCorpVault KeyManagerType = "HASHICORP_VAULT"
	KeyManagerTypeFilesystem     KeyManagerType = "FILESYSTEM"
)

type KeyVersionCreator

type KeyVersionCreator interface {
	// CreateKeyVersion creates a new key version for the given parent, returning
	// the ID of the new version. The parent key must already exist.
	CreateKeyVersion(ctx context.Context, parent string) (string, error)
}

KeyVersionCreator supports creating a new version of an existing key.

type KeyVersionDestroyer

type KeyVersionDestroyer interface {
	// DestroyKeyVersion destroys the given key version, if it exists. If the
	// version does not exist, it should not return an error.
	DestroyKeyVersion(ctx context.Context, id string) error
}

KeyVersionDestroyer supports destroying a key version.

type SigningKeyManager

type SigningKeyManager interface {
	// SigningKeyVersions returns the list of signing keys for the provided
	// parent. If the parent does not exist, it returns an error.
	SigningKeyVersions(ctx context.Context, parent string) ([]SigningKeyVersion, error)

	// CreateSigningKey creates a new signing key in the given parent, returning
	// the id. If the key already exists, it returns the key's id.
	CreateSigningKey(ctx context.Context, parent, name string) (string, error)

	KeyVersionCreator
	KeyVersionDestroyer
}

SigningKeyManager supports extended management of signing keys, versions, and rotation.

type SigningKeyVersion

type SigningKeyVersion interface {
	KeyID() string
	CreatedAt() time.Time
	DestroyedAt() time.Time
	Signer(ctx context.Context) (crypto.Signer, error)
}

SigningKeyVersion represents the necessary details that this application needs to manage signing keys in an external KMS.