secret

Documentation

Index

• Constants
• type Remote
• type Secret
  • func ParseSecret(s string) (Secret, error)
  • func (s Secret) String() string
  • func (s Secret) Unwrap(ciphertext []byte, associatedData []byte) ([]byte, error)
  • func (s Secret) Wrap(plaintext, associatedData []byte) ([]byte, error)
• type Store
  • func (s *Store) Create(name string, secret Secret) (err error)
  • func (s *Store) Delete(name string) error
  • func (s *Store) Get(name string) (Secret, error)
  • func (s *Store) StartGC(ctx context.Context, expiry, unusedExpiry time.Duration)

Constants

const MaxSize = 1 << 20 // 1 MiB

MaxSize is the max. size of a secret. A should be larger than 1 MiB.

Implementions of Remote should use this to limit the amount of data they read from the key-value store.

Types

type Remote

type Remote interface {
	// Create creates a new entry under the given
	// key and stores the given key-value pair
	// if and only if no such entry exists.
	//
	// If an entry already exists it does not replace
	// the value but returns kes.ErrKeyExists.
	Create(key, value string) error

	// Delete deletes the entry under the given key,
	// if any. Once an entry has been deleted a new
	// entry with the same key can be created.
	Delete(key string) error

	// Get returns the value associated with the given
	// key. It returns kes.ErrKeyNotFound if no entry
	// for the given key could be found.
	Get(key string) (string, error)
}

Remote is a key-value store for secrets Therefore, it stores keys and values as strings.

Remote is the interface that must be implemented by secret store backends, like Vault or AWS SecretsManager.

In general, values are not encrypted before they are stored at the Remote store. Therefore, an implementation must ensure that it: • stores values securely - i.e. encrypt them. • protect any network communication - i.e. via TLS.

type Secret

type Secret [32]byte

Secret is a 256 bit cryptographic key. It can be used to encrypt and decrypt data encryption keys (DEK).

func ParseSecret

func ParseSecret(s string) (Secret, error)

func (Secret) String

func (s Secret) String() string

func (Secret) Unwrap

func (s Secret) Unwrap(ciphertext []byte, associatedData []byte) ([]byte, error)

Unwrap decrypts and verifies the ciphertext, verifies the associated data and, if successful, returns the resuting plaintext. It returns an error if ciphertext is malformed or not authentic.

func (Secret) Wrap

func (s Secret) Wrap(plaintext, associatedData []byte) ([]byte, error)

Wrap encrypts and authenticates the plaintext, authenticates the associatedData and returns the resulting ciphertext.

It should be used to encrypt a session or data key provided as plaintext.

If the executing CPU provides AES hardware support, Wrap derives keys using AES and encrypts plaintexts using AES-GCM. Otherwise, Wrap derives keys using HChaCha20 and encrypts plaintexts using ChaCha20-Poly1305.

type Store

type Store struct {
	// Remote is the remote key-value store. Secrets
	// will be fetched from or written to this store.
	//
	// It must not be modified once the Store has been
	// used to fetch or store secrets.
	Remote Remote
	// contains filtered or unexported fields
}

Store is the local secret store connected to a remote key-value store.

It is responsible for caching secrets and storing/fetching values to/from the the Remote store.

func (*Store) Create

func (s *Store) Create(name string, secret Secret) (err error)

Create adds the given secret with the given name to the secret store. If there is already a secret with this name then it does not replace the secret and returns kes.ErrKeyExists.

func (*Store) Delete

func (s *Store) Delete(name string) error

Delete deletes the secret associated with the given name, if one exists.

func (*Store) Get

func (s *Store) Get(name string) (Secret, error)

Get returns the secret associated with the given name, if any. If no such secret exists it returns kes.ErrKeyNotFound.

func (*Store) StartGC

func (s *Store) StartGC(ctx context.Context, expiry, unusedExpiry time.Duration)

StartGC starts the cache garbage collection background process. The GC will discard all cached secrets after expiry. Further, it will discard all entries that haven't been used for unusedExpiry.

If expiry is 0 the GC will not discard any secrets. Similarly, if the unusedExpiry is 0 then the GC will not discard unused secrets.

There is only one garbage collection background process. Calling StartGC more than once has no effect.