Documentation
¶
Overview ¶
Package credentials keeps an app's secrets encrypted at rest: config/credentials.yml.enc holds KEY: value pairs sealed with AES-256-GCM under the master key in config/master.key (never committed) or LIDZA_MASTER_KEY (production). Every pack reads them the way it reads .env: pkg/env merges the decrypted values between the .env files and the process environment, so MAIL_API_KEY in the credentials is MAIL_API_KEY to the mail pack. Values saved at runtime (the admin pages) are held in the database by the db pack, encrypted with the same key, and override the file.
A value can be for one mode only: under a section named after the mode (dev:, production:) in the file, "dev.STRIPE_SECRET_KEY" to Set and Read. A mode reads the plain values and its own section, which wins; one sealed file holds a sandbox key for dev and the live key for production, and production needs only the master key.
Index ¶
- Constants
- Variables
- func Decrypt(key []byte, sealed string) ([]byte, error)
- func Encrypt(key, plain []byte) (string, error)
- func Format(values map[string]string) string
- func FormatValues(values map[string]string) string
- func Generate(dir string) (bool, error)
- func HasKey(dir string) bool
- func Key(dir string) ([]byte, error)
- func Mode() string
- func Names(dir string) []string
- func Overrides() map[string]string
- func Parse(text string) (map[string]string, error)
- func Read(dir string) (map[string]string, error)
- func Resolve(raw map[string]string, mode string) map[string]string
- func Set(dir string, values map[string]string) error
- func SetOverride(name, value string)
- func SetOverrides(values map[string]string)
- func Unset(dir string, names ...string) error
- func Values(dir string) map[string]string
- func Write(dir string, values map[string]string) error
- type Store
Constants ¶
const ( // MasterKeyFile holds the key, 32 bytes as 64 hex characters. MasterKeyFile = "config/master.key" // File is the sealed credentials. File = "config/credentials.yml.enc" // EnvMasterKey carries the key where no file should exist: production. EnvMasterKey = "LIDZA_MASTER_KEY" // EnvKeyOff=1 makes config/master.key unreadable to the process: lidza // test and verify set it, so tests never open the app's real // credentials. A test that needs a key sets EnvMasterKey itself. EnvKeyOff = "LIDZA_MASTER_KEY_OFF" )
Files and the environment.
const FileHeader = "" /* 270-byte string literal not displayed */
FileHeader is the comment Format writes at the top of the sealed file.
Variables ¶
var ErrKeyNotHere = errors.New("credentials: " + File + " is sealed with a master key this checkout lacks: put that key in " + MasterKeyFile + " or " + EnvMasterKey + " (from whoever set up the app); a new key could not open the file")
ErrKeyNotHere is Generate's refusal to make a key for a checkout whose credentials file was sealed with one it lacks: a clone, CI, another machine. A new key could not open the file.
var ErrNoKey = errors.New("credentials: no master key: " + MasterKeyFile + " is missing and " + EnvMasterKey + " is not set (lidza credentials init creates one)")
ErrNoKey is returned when neither the file nor the variable has a key.
Functions ¶
func FormatValues ¶ added in v0.1.110
FormatValues is Format without the file's header: values shown from somewhere else, such as the ones saved from the admin pages.
func Generate ¶
Generate writes a new master key to config/master.key (unless there is a key, in the file or LIDZA_MASTER_KEY), adds it to .gitignore, and seals an empty credentials file when there is none. It returns whether a key was created, and ErrKeyNotHere when the credentials file exists without its key: a new one would not open it.
func Mode ¶
func Mode() string
Mode is the run mode the values resolve for: LIDZA_MODE, else "production" (pkg/env.Mode, which imports this package).
func Parse ¶
Parse reads the flat YAML the file holds: one `KEY: value` per line, values optionally double-quoted (Go syntax), # comments.
func Read ¶
Read decrypts the credentials file, names as written: NAME, or mode.NAME for a value in a mode's section (Resolve picks a mode's). No file is no credentials.
func Resolve ¶
Resolve returns what mode reads from raw (Read's names): the plain names, with mode's "mode.NAME" entries over them; other modes' entries are left out.
func SetOverride ¶
func SetOverride(name, value string)
SetOverride sets one runtime value ("" removes it).
func SetOverrides ¶
SetOverrides replaces the runtime values.
func Values ¶
Values returns the file's values for the run mode (Resolve) with the runtime overrides applied; without a master key or a file, the overrides alone. This is what pkg/env merges.
Types ¶
type Store ¶
type Store interface {
Save(ctx context.Context, name, value string) error
Delete(ctx context.Context, name string) error
// Names lists what the store holds, sorted.
Names(ctx context.Context) ([]string, error)
}
Store keeps values saved while the app runs, encrypted with the master key; the db pack provides one in Postgres. Save and Delete also update the runtime overrides.
Source Files