kms

Documentation

Index

• type Config
• type Context
  • func (c Context) MarshalText() ([]byte, error)
• type DEK
  • func (d DEK) MarshalText() ([]byte, error)
  • func (d *DEK) UnmarshalText(text []byte) error
• type KMS
  • func New(keyID string, key []byte) (KMS, error)
  • func NewWithConfig(config Config) (KMS, error)
  • func Parse(s string) (KMS, error)
• type Status

Types

type Config

type Config struct {
	// Endpoints contains a list of KMS server
	// HTTP endpoints.
	Endpoints []string

	// DefaultKeyID is the key ID used when
	// no explicit key ID is specified for
	// a cryptographic operation.
	DefaultKeyID string

	// Certificate is the client TLS certificate
	// to authenticate to KMS via mTLS.
	Certificate tls.Certificate

	// RootCAs is a set of root CA certificates
	// to verify the KMS server TLS certificate.
	RootCAs *x509.CertPool
}

Config contains various KMS-related configuration parameters - like KMS endpoints or authentication credentials.

type Context

type Context map[string]string

Context is a set of key-value pairs that are associated with a generate data encryption key (DEK).

A KMS implementation may bind the context to the generated DEK such that the same context must be provided when decrypting an encrypted DEK.

func (Context) MarshalText

func (c Context) MarshalText() ([]byte, error)

MarshalText sorts the context keys and writes the sorted key-value pairs as canonical JSON object. The sort order is based on the un-escaped keys. It never returns an error.

type DEK

type DEK struct {
	KeyID      string
	Plaintext  []byte
	Ciphertext []byte
}

DEK is a data encryption key. It consists of a plaintext-ciphertext pair and the ID of the key used to generate the ciphertext.

The plaintext can be used for cryptographic operations - like encrypting some data. The ciphertext is the encrypted version of the plaintext data and can be stored on untrusted storage.

func (DEK) MarshalText

func (d DEK) MarshalText() ([]byte, error)

MarshalText encodes the DEK's key ID and ciphertext as JSON.

func (*DEK) UnmarshalText

func (d *DEK) UnmarshalText(text []byte) error

UnmarshalText tries to decode text as JSON representation of a DEK and sets DEK's key ID and ciphertext to the decoded values.

It sets DEK's plaintext to nil.

type KMS

type KMS interface {
	// Stat returns the current KMS status.
	Stat() (Status, error)

	// CreateKey creates a new key at the KMS with the given key ID.
	CreateKey(keyID string) error

	// GenerateKey generates a new data encryption key using the
	// key referenced by the key ID.
	//
	// The KMS may use a default key if the key ID is empty.
	// GenerateKey returns an error if the referenced key does
	// not exist.
	//
	// The context is associated and tied to the generated DEK.
	// The same context must be provided when the generated key
	// should be decrypted. Therefore, it is the callers
	// responsibility to remember the corresponding context for
	// a particular DEK. The context may be nil.
	GenerateKey(keyID string, context Context) (DEK, error)

	// DecryptKey decrypts the ciphertext with the key referenced
	// by the key ID. The context must match the context value
	// used to generate the ciphertext.
	DecryptKey(keyID string, ciphertext []byte, context Context) ([]byte, error)
}

KMS is the generic interface that abstracts over different KMS implementations.

func New

func New(keyID string, key []byte) (KMS, error)

New returns a single-key KMS that derives new DEKs from the given key.

func NewWithConfig

func NewWithConfig(config Config) (KMS, error)

NewWithConfig returns a new KMS using the given configuration.

func Parse

func Parse(s string) (KMS, error)

Parse parses s as single-key KMS. The given string is expected to have the following format:

<key-id>:<base64-key>

The returned KMS implementation uses the parsed key ID and key to derive new DEKs and decrypt ciphertext.

type Status

type Status struct {
	Name      string   // The name of the KMS
	Endpoints []string // A set of the KMS endpoints

	// DefaultKey is the key used when no explicit key ID
	// is specified. It is empty if the KMS does not support
	// a default key.
	DefaultKey string
}

Status describes the current state of a KMS.