kms

Documentation

Index

• func TestKmsDeleteAllKeys(t testing.TB, conn *db.DB)
• func TestKmsDeleteKeyPurpose(t testing.TB, conn *db.DB, purpose KeyPurpose)
• type ExternalWrappers
  • func (e *ExternalWrappers) Recovery() wrapping.Wrapper
  • func (e *ExternalWrappers) Root() wrapping.Wrapper
  • func (e *ExternalWrappers) WorkerAuth() wrapping.Wrapper
• type KeyPurpose
  • func ValidDekPurposes() []KeyPurpose
  • func (k KeyPurpose) String() string
• type Kms
  • func New(ctx context.Context, reader *db.Db, writer *db.Db, _ ...Option) (*Kms, error)
  • func NewUsingReaderWriter(ctx context.Context, reader db.Reader, writer db.Writer, _ ...Option) (*Kms, error)
  • func TestKms(t testing.TB, conn *db.DB, rootWrapper wrapping.Wrapper) *Kms
  • func (k *Kms) AddExternalWrappers(ctx context.Context, opt ...Option) error
  • func (k *Kms) CreateKeys(ctx context.Context, scopeId string, opt ...Option) error
  • func (k *Kms) GetDerivedPurposeCache() *sync.Map
  • func (k *Kms) GetExternalWrappers(ctx context.Context) *ExternalWrappers
  • func (k *Kms) GetWrapper(ctx context.Context, scopeId string, purpose KeyPurpose, opt ...Option) (wrapping.Wrapper, error)
  • func (k *Kms) ReconcileKeys(ctx context.Context, randomReader io.Reader, opt ...Option) error
  • func (k *Kms) VerifyGlobalRoot(ctx context.Context) error
• type Option
  • func WithKeyId(keyId string) Option
  • func WithLimit(limit int) Option
  • func WithOrderByVersion(orderBy db.OrderBy) Option
  • func WithRandomReader(randomReader io.Reader) Option
  • func WithReaderWriter(r db.Reader, w db.Writer) Option
  • func WithRecoveryWrapper(w wrapping.Wrapper) Option
  • func WithRootWrapper(w wrapping.Wrapper) Option
  • func WithScopeIds(scopeId ...string) Option
  • func WithWorkerAuthStorageWrapper(w wrapping.Wrapper) Option
  • func WithWorkerAuthWrapper(w wrapping.Wrapper) Option

Functions

func TestKmsDeleteAllKeys

func TestKmsDeleteAllKeys(t testing.TB, conn *db.DB)

TestKmsDeleteAllKeys allows you to delete all the keys for testing.

func TestKmsDeleteKeyPurpose

func TestKmsDeleteKeyPurpose(t testing.TB, conn *db.DB, purpose KeyPurpose)

TestKmsDeleteKeyPurpose allows you to delete a KeyPurpose for testing.

Types

type ExternalWrappers

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

ExternalWrappers holds wrappers defined outside of Boundary, e.g. in its configuration file.

func (*ExternalWrappers) Recovery

func (e *ExternalWrappers) Recovery() wrapping.Wrapper

Recovery returns the wrapper for recovery operations

func (*ExternalWrappers) Root

func (e *ExternalWrappers) Root() wrapping.Wrapper

Root returns the wrapper for root keys

func (*ExternalWrappers) WorkerAuth

func (e *ExternalWrappers) WorkerAuth() wrapping.Wrapper

WorkerAuth returns the wrapper for worker authentication

type KeyPurpose

type KeyPurpose uint

KeyPurpose allows an application to specify the reason they need a key; this is used to select which DEK to return

const (
	// KeyPurposeUnknown is the default, and indicates that a correct purpose
	// wasn't specified
	KeyPurposeUnknown KeyPurpose = iota

	// KeyPurposeDatabase is used for general encryption needs for most values
	// in the database, excluding the oplog
	KeyPurposeDatabase

	// KeyPurposeOplog is used for oplogs
	KeyPurposeOplog

	// KeyPurposeRecovery is used for recovery access
	KeyPurposeRecovery

	// KeyPurposeWorkerAuth is used for worker auth
	KeyPurposeWorkerAuth

	// KeyPurposeWorkerAuthStorage is used for worker credential storage
	KeyPurposeWorkerAuthStorage

	// KeyPurposeTokens is used for token encryption
	KeyPurposeTokens

	// KeyPurposeSessions is used as a base key to derive session-specific encryption keys
	KeyPurposeSessions

	// KeyPurposeOidc is used for encrypting oidc states included in
	// authentication URLs
	KeyPurposeOidc

	// KeyPurposeAudit is used for audit operations
	KeyPurposeAudit

	// KeyPurposeRootKey is used as the root key
	KeyPurposeRootKey
)

**************************************************************************** IMPORTANT: if you're adding a new KeyPurpose, you should consider whether or not existing scopes need this new type of key. If they do, then you may want to add the new key into kms.ReconcileKeys(...) ****************************************************************************

func ValidDekPurposes

func ValidDekPurposes() []KeyPurpose

ValidDekPurposes returns the current list of valid DEK key purposes

func (KeyPurpose) String

func (k KeyPurpose) String() string

String returns the key purpose cast as a string, just so it can be called as a function instead of direct casting elsewhere, yw

type Kms

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

Kms is a way to access wrappers for a given scope and purpose. Since keys can never change, only be added or (eventually) removed, it opportunistically caches, going to the database as needed.

func New

func New(ctx context.Context, reader *db.Db, writer *db.Db, _ ...Option) (*Kms, error)

New creates a Kms using the provided reader and writer. No options are currently supported.

func NewUsingReaderWriter

func NewUsingReaderWriter(ctx context.Context, reader db.Reader, writer db.Writer, _ ...Option) (*Kms, error)

NewUsingReaderWriter creates a Kms using the provided reader and writer. No options are currently supported.

func TestKms

func TestKms(t testing.TB, conn *db.DB, rootWrapper wrapping.Wrapper) *Kms

TestKms creates a kms for testing.

func (*Kms) AddExternalWrappers

func (k *Kms) AddExternalWrappers(ctx context.Context, opt ...Option) error

AddExternalWrappers allows setting the external keys.

func (*Kms) CreateKeys

func (k *Kms) CreateKeys(ctx context.Context, scopeId string, opt ...Option) error

CreateKeys creates the root key and DEKs returns a map of the new keys. Supports the WithRandomReader(...) and WithReaderWriter(...) options. When WithReaderWriter(...) is used the caller is responsible for managing the transaction which allows this capability to be shared with the iam repo when it's creating Scopes.

func (*Kms) GetDerivedPurposeCache

func (k *Kms) GetDerivedPurposeCache() *sync.Map

GetDerivedPurposeCache returns the raw derived purpose cache

func (*Kms) GetExternalWrappers

func (k *Kms) GetExternalWrappers(ctx context.Context) *ExternalWrappers

GetExternalWrappers returns the Kms' ExternalWrappers

func (*Kms) GetWrapper

func (k *Kms) GetWrapper(ctx context.Context, scopeId string, purpose KeyPurpose, opt ...Option) (wrapping.Wrapper, error)

GetWrapper returns a wrapper for the given scope and purpose. When a keyId is passed, it will ensure that the returning wrapper has that key ID in the multiwrapper. This is not necessary for encryption but should be supplied for decryption.

func (*Kms) ReconcileKeys

func (k *Kms) ReconcileKeys(ctx context.Context, randomReader io.Reader, opt ...Option) error

ReconcileKeys will reconcile the keys in the kms against known possible issues. This function reconciles the global scope unless the WithScopeIds(...) option is provided

func (*Kms) VerifyGlobalRoot

func (k *Kms) VerifyGlobalRoot(ctx context.Context) error

VerifyGlobalRoot will verify that the global root wrapper is reasonable.

type Option

type Option func(*options)

Option - how Options are passed as arguments

func WithKeyId

func WithKeyId(keyId string) Option

WithKeyId allows specifying a key ID that should be found in a scope's multiwrapper; if it is not found, keys will be refreshed

func WithLimit

func WithLimit(limit int) Option

WithLimit provides an option to provide a limit. Intentionally allowing negative integers. If WithLimit < 0, then unlimited results are returned. If WithLimit == 0, then default limits are used for results.

func WithOrderByVersion

func WithOrderByVersion(orderBy db.OrderBy) Option

WithOrderByVersion provides an option to specify ordering by the CreateTime field.

func WithRandomReader

func WithRandomReader(randomReader io.Reader) Option

WithRandomReader(...) option allows an optional random reader to be provided. By default the reader from crypto/rand will be used.

func WithReaderWriter

func WithReaderWriter(r db.Reader, w db.Writer) Option

WithReaderWriter allows the caller to pass an inflight transaction to be used for all database operations. If WithReaderWriter(...) is used, then the caller is responsible for managing the transaction. The purpose of the WithReaderWriter(...) option is to allow the caller to create the scope and all of its keys in the same transaction.

func WithRecoveryWrapper

func WithRecoveryWrapper(w wrapping.Wrapper) Option

WithRecoveryWrapper sets the recovery wrapper for a given scope

func WithRootWrapper

func WithRootWrapper(w wrapping.Wrapper) Option

WithRootWrapper sets the external root wrapper for a given scope

func WithScopeIds

func WithScopeIds(scopeId ...string) Option

WithScopeIds allows the specifying of optional scope ids.

func WithWorkerAuthStorageWrapper

func WithWorkerAuthStorageWrapper(w wrapping.Wrapper) Option

WithWorkerAuthStorageWrapper sets the external pki worker storage wrapper for a given scope

func WithWorkerAuthWrapper

func WithWorkerAuthWrapper(w wrapping.Wrapper) Option

WithWorkerAuthWrapper sets the external worker authentication wrapper for a given scope