db

Documentation

Overview

Package db provides a secrets database that is encrypted at rest.

The database is encrypted at rest using a Data Encryption Key (DEK). The DEK is stored alongside the database, but is itself encrypted at rest using a Key Encryption Key (KEK). In production, the KEK should be stored in a key management system like AWS KMS.

This layering of encryption means access to the remote KMS is required at Open time, to decrypt the local DEK that in turn can decrypt the database proper. But once the DEK has been decrypted locally, we can decrypt and re-encrypt the database at will (e.g. to save changes) without having a dependency on a remote system.

Index

• Variables
• type Caller
• type DB
  • func Open(path string, key tink.AEAD, auditLog *audit.Writer) (*DB, error)
  • func (db *DB) Activate(caller Caller, name string, version api.SecretVersion) error
  • func (db *DB) Delete(caller Caller, name string) error
  • func (db *DB) DeleteVersion(caller Caller, name string, version api.SecretVersion) error
  • func (db *DB) Get(caller Caller, name string) (*api.SecretValue, error)
  • func (db *DB) GetConditional(caller Caller, name string, oldVersion api.SecretVersion) (*api.SecretValue, error)
  • func (db *DB) GetVersion(caller Caller, name string, version api.SecretVersion) (*api.SecretValue, error)
  • func (db *DB) Info(caller Caller, name string) (*api.SecretInfo, error)
  • func (db *DB) List(caller Caller) ([]*api.SecretInfo, error)
  • func (db *DB) Path() string
  • func (db *DB) Put(caller Caller, name string, value []byte) (api.SecretVersion, error)
  • func (db *DB) WriteGen() uint64

Variables

var (
	// ErrAccessDenied is the error returned by DB methods when the
	// caller lacks necessary permissions.
	ErrAccessDenied = errors.New("access denied")
	// ErrNotFound is the error returned by DB methods when the
	// database lacks a necessary secret or secret version.
	ErrNotFound = errors.New("not found")
)

Types

type Caller

type Caller struct {
	// Principal is the caller identity that gets written to audit
	// logs.
	Principal audit.Principal
	// Permissions are the permissions the caller has.
	Permissions acl.Rules
}

Caller encapsulates a caller identity. It is required by all database methods. The contents of Caller should be derived from a tailsale WhoIs API call.

type DB

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

DB is an encrypted secrets database.

func Open

func Open(path string, key tink.AEAD, auditLog *audit.Writer) (*DB, error)

Open loads the secrets database at path, decrypting it using key. If no database exists at path, a new empty database is created.

func (*DB) Activate

func (db *DB) Activate(caller Caller, name string, version api.SecretVersion) error

Activate changes the active version of the secret called name to version.

func (*DB) Delete

func (db *DB) Delete(caller Caller, name string) error

Delete deletes all the versions of a secret. If the specified secret does not exist, this is a no-op without error, provided the caller has access to delete things at all.

func (*DB) DeleteVersion

func (db *DB) DeleteVersion(caller Caller, name string, version api.SecretVersion) error

DeleteVersion deletes the specified version of a secret. It reports an error without change if version is the active version.

func (*DB) Get

func (db *DB) Get(caller Caller, name string) (*api.SecretValue, error)

Get returns a secret's active value.

func (*DB) GetConditional

func (db *DB) GetConditional(caller Caller, name string, oldVersion api.SecretVersion) (*api.SecretValue, error)

GetConditional returns a secret's active value if it is different from oldVersion. If the active version is the same as oldVersion, it reports api.ErrValueNotChanged.

func (*DB) GetVersion

func (db *DB) GetVersion(caller Caller, name string, version api.SecretVersion) (*api.SecretValue, error)

GetVersion returns a secret's value at a specific version.

func (*DB) Info

func (db *DB) Info(caller Caller, name string) (*api.SecretInfo, error)

Info returns metadata for the given secret.

func (*DB) List

func (db *DB) List(caller Caller) ([]*api.SecretInfo, error)

List returns secret metadata for all secrets on which at least one member of 'from' has acl.ActionInfo permissions.

func (*DB) Path

func (db *DB) Path() string

Path returns the path to the database file on disk.

func (*DB) Put

func (db *DB) Put(caller Caller, name string, value []byte) (api.SecretVersion, error)

Put writes value to the secret called name. If the secret already exists, value is saved as a new inactive version. Otherwise, value is saved as the initial version of the secret and immediately set active. On success, returns the secret version for the new value.

func (*DB) WriteGen

func (db *DB) WriteGen() uint64

WriteGen returns a process-local "write generation" for the DB. The write generation is a positive value that increments whenever a change is saved to disk, and can be used as a coarse change detection mechanism.