keys

package
v0.12.1 Latest Latest
Warning

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

 Go to latest Published: Oct 15, 2020 License: Apache-2.0 Imports: 42 Imported by: 22

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 TestEncryptionKey added in v0.7.0 

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 added in v0.7.0 

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 added in v0.8.0 

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 added in v0.8.0 

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 added in v0.8.0 

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 added in v0.8.0 

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 added in v0.5.0 

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

func (*CloudKMSSigningKeyVersion) CreatedAt added in v0.5.0 

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

func (*CloudKMSSigningKeyVersion) DestroyedAt added in v0.5.0 

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

func (*CloudKMSSigningKeyVersion) KeyID added in v0.5.0 

func (k *CloudKMSSigningKeyVersion) KeyID() string

func (*CloudKMSSigningKeyVersion) Signer added in v0.5.0 

func (k *CloudKMSSigningKeyVersion) Signer(ctx context.Context) (crypto.Signer, error)

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 added in v0.7.0 

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 added in v0.7.0 

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 added in v0.7.0 

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 added in v0.7.0 

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 added in v0.7.0 

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 added in v0.7.0 

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 added in v0.7.0 

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 added in v0.7.0 

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 added in v0.7.0 

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 added in v0.7.0 

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 added in v0.7.0 

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 added in v0.5.1 

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 added in v0.5.1 

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 added in v0.5.1 

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 added in v0.5.0 

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 valut, the keys must be created with 

`derived=true`

func (*HashiCorpVault) CreateKeyVersion added in v0.6.0 

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

CreateKeyVersion rotates the given key.

func (*HashiCorpVault) CreateSigningKey added in v0.6.0 

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 added in v0.6.0 

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 added in v0.6.0 

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 

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

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 wile enctypt a byte array along with accompaning 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 descrypt a previously encrypted byte array along with accompaning 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 added in v0.7.0 

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 added in v0.5.1 

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 added in v0.5.1 

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 added in v0.5.1 

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 added in v0.5.0 

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.

Source Files

View all Source files

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.