keys

package
v0.28.0 Latest Latest
Warning

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

 Go to latest Published: May 7, 2021 License: Apache-2.0 Imports: 24 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 ParseECDSAPublicKey added in v0.20.0 

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

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

func RegisterManager added in v0.22.0 

func RegisterManager(name string, fn KeyManagerFunc)

RegisterManager registers a new key manager with the given name. If a manager is already registered with the given name, it panics. Managers are usually registered via an init function.

func RegisteredManagers added in v0.22.0 

func RegisteredManagers() []string

RegisteredManagers returns the list of the names of the registered key managers.

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 Config 

type Config struct {
	// Type is the type of the key manager.
	Type string `env:"KEY_MANAGER, default=FILESYSTEM"`

	// 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 (*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 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, cfg *Config) (KeyManager, error)

KeyManagerFor returns the key manager with the given name, or an error if one does not exist.

func NewFilesystem added in v0.7.0 

func NewFilesystem(ctx context.Context, cfg *Config) (KeyManager, 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 TestKeyManager added in v0.7.0 

func TestKeyManager(tb testing.TB) KeyManager

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

type KeyManagerFunc added in v0.22.0 

type KeyManagerFunc func(context.Context, *Config) (KeyManager, error)

KeyManagerFunc is a func that returns a key manager or error.

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.