Help us shape the future of Go! Take the 2026 Go Developer Survey

secret

package
v0.145.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 15, 2026 License: Apache-2.0 Imports: 44 Imported by: 0

Documentation

Overview

Package secret is beekeeper secret: the credential operations beekeeper runs in its own process so that no agent reads a value. sops and op run here, the values they answer stay in memory for the one operation, and what an operation returns is key names, lengths, equality and keyed fingerprints, never a value. Nothing is written in plaintext: a SOPS file is written encrypted, from sops' own output.

Index

Constants

View Source 
const (
	// FileRef starts the reference of an identity file on the host.
	FileRef = "file://"
	// StoreRef starts the reference of an entry of the person's own
	// credential store; with no entry, the store's search finds it by the
	// file's recipients.
	StoreRef = "store://"
)

The references of an age identity besides a vault field.

View Source 
const (
	Equal     = "equal"
	Different = "different"
	OnlyA     = "only in a"
	OnlyB     = "only in b"
)

The states compare answers per key.

View Source 
const (
	VaultUnlock    = "unlock"
	VaultLock      = "lock"
	VaultStatus    = "status"
	VaultStore     = "store"
	VaultStoreItem = "store-item"
)

The socket's operations.

View Source 
const BrokerUnit = "beekeeper-sandbox.service"

BrokerUnit is the systemd user unit whose main process is the broker.

View Source 
const FieldManager = "beekeeper-secret"

FieldManager is the field manager a copied key is written under.

View Source 
const GitUser = "oauth2"

GitUser is the user name the askpass helper answers by default: GitLab takes any for a token, GitHub too.

View Source 
const K8sRef = "k8s://"

K8sRef starts a reference to a key of a Kubernetes Secret as a source: k8s://<context>/<namespace>/<name>/<key>, and after # the dotted path of one value inside the YAML (or JSON) document the key holds.

View Source 
const Locked = "vault locked: waiting for the broker's sign-in"

Locked is the message of a call that waits on the person's unlock.

View Source 
const MaxItemBytes = 4 * MaxStoreBytes

MaxItemBytes bounds the values of one store into an item together: a GitHub App's credentials, its private key included, fit many times over.

View Source 
const MaxStoreBytes = 32 << 10

MaxStoreBytes bounds a stored value: a private key or a certificate chain fits, a file that is no credential does not.

View Source 
const None = "none"

None opens the identity of a recipient beekeeper cannot decrypt for.

View Source 
const PlatformPrefix = "platform://"

PlatformPrefix opens a PlatformRef.

Variables

View Source 
var AskpassArgs = []string{"secret", "askpass"}

AskpassArgs are the arguments after the binary that make beekeeper the git askpass helper: secret askpass <socket> <prompt>.

View Source 
var ErrLocked = errors.New("vault locked")

ErrLocked is a vault the person did not unlock in time.

View Source 
var ErrNoAgeIdentity = errors.New("no age identity")

ErrNoAgeIdentity marks a SOPS file whose age recipients no identity beekeeper can reach decrypts for.

View Source 
var ErrSecretLike = errors.New("looks secret")

ErrSecretLike is reveal's refusal of a leaf the classifier takes for a secret.

View Source 
var ErrSetUp = errors.New("already set up")

ErrSetUp is a token file that already holds a token: setup creates one service account once, a second would orphan the first.

View Source 
var ErrVault = errors.New("the shared vault cannot be read")

ErrVault marks a failure to read the shared vault: none configured, no token, or op answering an error or no answer in time.

Functions

func AgeInstallationItem added in v0.114.0 

func AgeInstallationItem(installation string) string

AgeInstallationItem is the title of the vault item that holds the identity of installation's recipient.

func AgeItemRef added in v0.109.0 

func AgeItemRef(vault, recipient string) string

AgeItemRef is the op:// reference of recipient's identity in vault.

func AgeItemTitle added in v0.109.0 

func AgeItemTitle(recipient string) string

AgeItemTitle is the title of the vault item that holds recipient's identity.

func ApplySecret added in v0.81.0 

func ApplySecret(ctx context.Context, kubeconfig []byte, t KubeTarget, value []byte) error

ApplySecret is the SecretApplier of a real cluster: WriteSecretKey through the kubeconfig's cluster.

func Askpass added in v0.119.0 

func Askpass(sock, prompt string, w io.Writer) error

Askpass is the helper's side: it asks the socket for prompt's answer and writes it to w, for git to read. A prompt beekeeper answers nothing to fails.

func AskpassMain added in v0.119.0 

func AskpassMain(args []string, stdout, stderr io.Writer) int

AskpassMain runs the askpass helper for args after AskpassArgs, answering the exit code.

func Charsets 

func Charsets() []string

Charsets names the character sets, sorted.

func ClearClipboard added in v0.118.0 

func ClearClipboard(ctx context.Context, run Runner) error

ClearClipboard empties the Wayland clipboard (wl-copy --clear), so that a stored value does not wait there for the next paste.

func Clipboard added in v0.118.0 

func Clipboard(ctx context.Context, run Runner) (string, error)

Clipboard reads the Wayland clipboard through wl-paste, trimmed of the whitespace a selection drags along; "" when nothing is copied.

func Consumer 

func Consumer(argv []string) error

Consumer allows a command to take a value on stdin: one that reads a secret from stdin and stores it without printing it (gitlab-rails runner's code reading STDIN among them), or kubectl exec -i handing stdin to such a command in a pod. git takes a value through GitConsumer's askpass path instead.

func ConsumerContext added in v0.96.0 

func ConsumerContext(argv []string) string

ConsumerContext is the kube context a kubectl exec consumer names, "" for any other consumer.

func Exec 

func Exec(ctx context.Context, dir string, env []string, stdin io.Reader, name string, args ...string) ([]byte, error)

Exec is the Runner of the real tools, found on PATH or in the Go tool directories (proc.LookPath): the sandbox broker's calls run with the service manager's PATH, without the directory kind lives in.

func Expired added in v0.91.0 

func Expired(stderr string) bool

Expired reports whether op's error says the session is gone.

func Generate 

func Generate(n int, charset string) (string, error)

Generate draws a value of n characters from a named set.

func GitConsumer added in v0.119.0 

func GitConsumer(argv []string) error

GitConsumer allows a git operation that authenticates over HTTPS with the credential beekeeper's askpass helper answers: git [-C <dir>] clone, fetch, push or ls-remote, without an option that sets configuration or names a program to run (a credential helper or an upload-pack would get the credential's way in).

func ImportRecipient added in v0.139.0 

func ImportRecipient(path string) (string, error)

ImportRecipient is the one age recipient path's .sops.yaml declares, the recipient whose identity an import stores. For a SOPS file it is the file's recipient (its metadata's when encrypted, else its creation rule's); for a directory the recipient of the creation rule sops applies to the files below it (the first without a path_regex or whose path_regex matches the directory), else the one recipient all its creation rules share. No rule, or several recipients, is an error naming path.

func NeedsVault added in v0.91.0 

func NeedsVault(args []string) bool

NeedsVault reports whether a beekeeper secret call's arguments name the shared vault: an op:// reference, a flag's value included.

func NewestFile added in v0.118.0 

func NewestFile(dir, pattern string) (string, error)

NewestFile is the newest regular file in dir whose name matches the glob pattern, "" when none.

func ParseItem added in v0.125.0 

func ParseItem(s string) (vault, item string, err error)

ParseItem reads op://<vault>/<item>, an item of the shared vault.

func ParseSignin added in v0.91.0 

func ParseSignin(out []byte) (string, string, error)

ParseSignin reads the session op signin printed: its variable's name and the token.

func Peer added in v0.91.0 

func Peer(c net.Conn) error

Peer checks that the other end of c is this user's broker: the main process of BrokerUnit, whose unit runs this very binary. The keeper's socket path is the person's, but a process that took the path first must not get a session. The broker is undumpable (Protect), so its /proc/<pid>/exe belongs to root and tells nothing; systemd names the process and the binary instead.

func ProducerEnv added in v0.119.0 

func ProducerEnv(environ, drop []string) []string

ProducerEnv is environ without the variables that carry a secret: the vault's credentials, sops' age identity and those whose names match one of the globs of drop (secret.env).

func Protect added in v0.91.0 

func Protect() error

Protect makes this process undumpable: no other process of the user reads its memory or environment through /proc or ptrace, and it leaves no core dump with the session in it.

func ReadSecret added in v0.111.0 

func ReadSecret(ctx context.Context, kubeconfig []byte, t KubeTarget) ([]byte, error)

ReadSecret is the SecretReader of a real cluster.

func ReadValueFile added in v0.118.0 

func ReadValueFile(path string) (string, error)

ReadValueFile reads a file holding one value, of at most MaxStoreBytes.

func ServeVault added in v0.91.0 

func ServeVault(ctx context.Context, path string, k *Keeper, store Storer, storeItem ItemStorer) error

ServeVault answers the keeper's socket at path until ctx ends; store writes what a store request hands over and storeItem what a store-item does (nil refuses one).

func Shred added in v0.118.0 

func Shred(path string) error

Shred overwrites path with random bytes and removes it: a downloaded key file leaves no plaintext behind once the vault holds it.

func SocketPath added in v0.91.0 

func SocketPath() (string, error)

SocketPath is the keeper's socket under the runtime directory.

func StatePath added in v0.93.0 

func StatePath() (string, error)

StatePath is the broker's vault state, next to the keeper's socket: whether it holds a session, since and until when, never the session. The watch reads it.

func Uptime added in v0.108.0 

func Uptime() (time.Duration, error)

Uptime is how long the machine is up, from /proc/uptime.

func WaitsPath added in v0.91.0 

func WaitsPath() (string, error)

WaitsPath is the broker's list of waiting calls, next to the keeper's socket: the watch and beekeeper status read it, no sandboxed session writes it.

func WriteSecretKey added in v0.108.3 

func WriteSecretKey(ctx context.Context, c client.Client, t KubeTarget, value []byte) error

WriteSecretKey writes value into the one key of the Secret t names: a merge patch of that key alone, so the Secret's other keys, labels and annotations stay whoever wrote them; a Secret absent is created with the key. A server-side apply would own the whole data of the Secret under FieldManager and drop the keys an earlier copy wrote.

func WriteState added in v0.93.0 

func WriteState(path string, st VaultState) error

WriteState replaces the broker's vault state, through a rename.

func WriteWaits added in v0.91.0 

func WriteWaits(path string, ws []VaultWait) error

WriteWaits replaces the list of waiting calls, through a rename.

Types

type AgeIdentity added in v0.92.0 

type AgeIdentity struct {
	// Recipient is the age recipient (age1…) the identity decrypts for.
	Recipient string
	// Path matches the file's absolute path; nil matches by recipient only.
	Path *regexp.Regexp
	// Ref is the op:// field, the file:// identity file or the store://
	// entry that holds the identity (AGE-SECRET-KEY-1…, an identity file's
	// comments allowed).
	Ref string
	// contains filtered or unexported fields
}

AgeIdentity is where beekeeper finds the age identity of a SOPS file none of sops' own sources holds: a field of the shared vault, an identity file on the host or an entry of the person's own credential store, read in beekeeper's process and given to the one sops call's environment alone.

type CaptureOptions added in v0.119.0 

type CaptureOptions struct {
	// Producer is the command that prints the value, run in this process.
	Producer []string
	// Env is the producer's environment ([ProducerEnv]).
	Env []string
	// Stderr receives the producer's stderr; nil discards it.
	Stderr io.Writer
	// JQ is a jq filter that picks the value out of the producer's JSON
	// output, one string; empty takes the whole output, its line end
	// trimmed.
	JQ string
	// Vault is the shared vault's field that holds the value first.
	Vault Ref
	// Docker writes the value as the .dockerconfigjson of a
	// kubernetes.io/dockerconfigjson Secret instead of at a path.
	Docker *DockerConfig
	// New is the Secret a file absent so far starts as.
	New *NewSecret
}

CaptureOptions are the producer whose stdout a capture takes the value from and where the value goes besides the SOPS path.

type CaptureResult added in v0.119.0 

type CaptureResult struct {
	Key         string `json:"key"`
	Bytes       int    `json:"bytes"`
	Fingerprint string `json:"fingerprint"`
}

CaptureResult is what a capture answers: where the value went, its length as written and its keyed fingerprint.

type Carrier added in v0.73.0 

type Carrier struct {
	Ref    string `json:"ref"`
	Base64 bool   `json:"base64,omitempty"`
}

Carrier is a SOPS path that carried a rotated value: the value itself, or its base64 form (a Kubernetes Secret's data).

type Credential added in v0.109.0 

type Credential struct {
	Name string
	Ref  Ref
}

Credential is a value a process beekeeper starts gets in its environment: the variable Name, from Ref.

type DockerConfig added in v0.119.0 

type DockerConfig struct {
	Registry string
	Username string
}

DockerConfig is the kubernetes.io/dockerconfigjson shape a captured registry password takes: the registry it pulls from and the user it authenticates.

type Encoding added in v0.111.0 

type Encoding struct {
	// Base64 encodes the value in standard base64.
	Base64 bool `json:"base64,omitempty"`
	// User, when set, encodes base64("<user>:<value>"), an HTTP Basic
	// credential.
	User string `json:"user,omitempty"`
}

Encoding transforms a value before it is written, inside beekeeper's process: a consumer that injects a value verbatim (a gateway's "Authorization: Basic <value>") needs the encoded form, which no caller could otherwise make without reading the value. The zero Encoding writes the value as it is.

func ParseEncoding added in v0.111.0 

func ParseEncoding(s string) (Encoding, error)

ParseEncoding reads base64 or basic:<user>; "" is the value as it is.

func (Encoding) Apply added in v0.111.0 

func (e Encoding) Apply(v string) string

Apply is v in the encoding.

func (Encoding) IsZero added in v0.111.0 

func (e Encoding) IsZero() bool

IsZero is whether the encoding writes the value as it is.

func (Encoding) String added in v0.111.0 

func (e Encoding) String() string

String is the encoding as the flag names it, "" for none.

type Field added in v0.114.0 

type Field struct {
	Path  string `json:"path"`
	Value string `json:"value"`
}

Field is a revealed leaf of a SOPS file: its dotted path and its value, configuration the classifier found no secret in.

type Handover added in v0.109.0 

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

Handover holds the values of a process's credentials, read from their references, until they are written into its environment: NAME=value lines for a process that reads its environment that way before it runs, an omp agent's shell from its inbox. The values live here and go to the writer alone.

func (*Handover) WriteTo added in v0.109.0 

func (h *Handover) WriteTo(w io.Writer) (int64, error)

WriteTo writes the NAME=value lines to w.

type ItemField added in v0.125.0 

type ItemField struct {
	Label string `json:"label"`
	Value string `json:"value"`
	Plain bool   `json:"plain,omitempty"`
}

ItemField is one field of a store into a vault item: its label, its value and whether it is configuration, a plain string, rather than a secret, which is concealed.

type ItemStorer added in v0.125.0 

type ItemStorer func(ctx context.Context, env, item string, fields []ItemField) ([]Stored, error)

ItemStorer writes fields into the vault item (op://<vault>/<item>) with the session env, in one op call, and answers what it wrote per field.

type Keeper added in v0.91.0 

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

Keeper holds the vault session in memory, for its lifetime at most.

func NewKeeper added in v0.91.0 

func NewKeeper(lifetime time.Duration, changed func(VaultState)) *Keeper

NewKeeper is a locked keeper that holds a session for lifetime and tells changed (nil: no one) each new state.

func (*Keeper) Drop added in v0.97.0 

func (k *Keeper) Drop(reason string, now time.Time)

Drop forgets a session op no longer takes, and says why until the next unlock.

func (*Keeper) Env added in v0.91.0 

func (k *Keeper) Env() string

Env is the session's environment entry for op, "" while locked.

func (*Keeper) Lock added in v0.91.0 

func (k *Keeper) Lock()

Lock forgets the session: the person's lock, or one op no longer takes.

func (*Keeper) State added in v0.93.0 

func (k *Keeper) State() VaultState

State is whether the keeper holds a session, since when and until when.

func (*Keeper) Unlock added in v0.91.0 

func (k *Keeper) Unlock(name, token string, now time.Time) error

Unlock takes the session a sign-in printed, until its lifetime passes.

func (*Keeper) Wait added in v0.91.0 

func (k *Keeper) Wait(ctx context.Context) error

Wait blocks until the keeper holds a session or ctx ends (ErrLocked).

type Key 

type Key struct {
	Name  string `json:"name"`
	Bytes int    `json:"bytes"`
}

Key is a key name and the length of its value, all an answer tells.

type KubeTarget added in v0.81.0 

type KubeTarget struct {
	Context   string `json:"context"`
	Namespace string `json:"namespace"`
	Name      string `json:"name"`
	Key       string `json:"key"`
}

KubeTarget is one key of a Secret: <context>/<namespace>/<name>/<key>.

func ParseKubeTarget added in v0.81.0 

func ParseKubeTarget(s string) (KubeTarget, error)

ParseKubeTarget reads <context>/<namespace>/<name>/<key>.

func (KubeTarget) KindCluster added in v0.81.0 

func (t KubeTarget) KindCluster() string

KindCluster is the kind cluster a kind-<cluster> context names, "" for any other context.

func (KubeTarget) String added in v0.81.0 

func (t KubeTarget) String() string

String is the target as a log and an answer name it.

type NewSecret added in v0.96.0 

type NewSecret struct {
	Name      string
	Namespace string
}

NewSecret is the Kubernetes Secret a new SOPS file starts as.

type Ops 

type Ops struct {
	Run Runner
	// Vault is the shared 1Password vault, the only one an op:// reference
	// may name; empty refuses every op:// reference.
	Vault string
	// Token is the vault's service account token, which only op's own
	// environment gets; empty refuses every op:// reference.
	Token string
	// Session reads the vault through the person's own signed-in op
	// session (OP_SESSION_* in the caller's environment) instead of a
	// service account: the way to a vault no service account can be
	// granted, such as a person's Employee vault.
	Session bool
	// Env is what op's environment gets besides this process's own in
	// session mode: the broker's own calls give the vault session here; a
	// brokered child carries it in its environment already.
	Env []string
	// Fingerprint is the keyed hash fingerprint answers with.
	Fingerprint func(value string) string
	// Apply writes a key of a Secret; nil is [ApplySecret].
	Apply SecretApplier
	// Read reads a key of a Secret; nil is [ReadSecret].
	Read SecretReader
	// Kubeconfig are the kubeconfig files a k8s:// reference's context is
	// resolved in, outside a kind lab (whose kubeconfig kind answers);
	// empty refuses every such reference.
	Kubeconfig []string
	// Encode transforms the value a copy writes, set writes besides the
	// vault, and fingerprint answers for; the zero Encoding keeps it as it is.
	Encode Encoding
	// Ages are the age identities of the shared vault, an identity file or
	// the person's own credential store for the SOPS files sops' own
	// sources hold none for.
	Ages []AgeIdentity
	// AgeVaults are the vaults besides Vault that age identities are read
	// from: an op:// entry of Ages may name one, and the item of a SOPS
	// file's installation ([AgeInstallationItem]) is looked up in Vault and
	// each of them.
	AgeVaults []string
	// Store is the person's own credential store a store:// age identity
	// is read from.
	Store Store
	// Index is the value scanner's index reveal checks a value against, its
	// indexed secrets and token patterns; nil checks the patterns alone.
	Index *guard.Index
	// Installations are the installations' names, which a SOPS file's path
	// under its .sops.yaml carries as a directory: a refusal names the one
	// whose recipient has no identity.
	Installations []string
}

Ops are the operations over one configuration.

func (*Ops) AgeNeedsIdentity added in v0.94.0 

func (o *Ops) AgeNeedsIdentity(dir string, args []string) bool

AgeNeedsIdentity reports whether decrypting one of the SOPS files args name, relative to dir (the working directory when empty), takes an identity of secret.ageIdentities, from the vault, a file or the store.

func (*Ops) AgeNeedsVault added in v0.92.0 

func (o *Ops) AgeNeedsVault(dir string, args []string) bool

AgeNeedsVault reports whether decrypting one of the SOPS files args name, relative to dir (the working directory when empty), takes an age identity from the shared vault.

func (*Ops) Capture added in v0.119.0 

func (o *Ops) Capture(ctx context.Context, dst Ref, opt CaptureOptions) (CaptureResult, error)

Capture runs the producer and writes the value it prints (one string of its JSON output with opt.JQ) to the shared vault's field first when one is given, then into the SOPS path in o.Encode, or as a Secret's .dockerconfigjson with opt.Docker. Every check (the references, the creation rule, the filter) runs before the producer does: a credential that is printed once is not spent on a call that could not store it. The producer's stdout is never answered.

func (*Ops) Compare 

func (o *Ops) Compare(ctx context.Context, a, b Ref) ([]Verdict, error)

Compare answers per key whether a and b hold the same values. Two single references compare as one value; two whole files key by key.

func (*Ops) CopyFile 

func (o *Ops) CopyFile(ctx context.Context, src Ref, dst, name, namespace string) ([]Key, error)

CopyFile copies a whole SOPS file to a new one, encrypted under the destination's creation rules, with a Kubernetes object's metadata.name and metadata.namespace rewritten when given. It answers the keys and their lengths.

func (*Ops) CopyToConsumer 

func (o *Ops) CopyToConsumer(ctx context.Context, src Ref, argv []string, in Stdin) (int, string, error)

CopyToConsumer runs an allowed consumer with the value on stdin, shaped by in. It answers the consumer's exit code and its output with the value redacted.

func (*Ops) CopyToGit added in v0.119.0 

func (o *Ops) CopyToGit(ctx context.Context, src Ref, argv []string, user string) (int, string, error)

CopyToGit runs an allowed git operation with GIT_ASKPASS answering user and the value, which never reaches git's argv, its environment or a file. It answers git's exit code and its output with the value redacted.

func (*Ops) CopyToSecret added in v0.81.0 

func (o *Ops) CopyToSecret(ctx context.Context, src Ref, t KubeTarget) (int, error)

CopyToSecret copies one value into a key of a Secret in a kind cluster, reached with the admin kubeconfig kind answers, which stays in memory like the value. It answers the value's length. Which contexts a caller may write to is the caller's to check.

func (*Ops) CopyValue 

func (o *Ops) CopyValue(ctx context.Context, src, dst Ref) (int, error)

CopyValue copies one value into a path of a SOPS file, creating the file or the key when absent. It answers the value's length.

func (*Ops) CopyValues added in v0.108.0 

func (o *Ops) CopyValues(ctx context.Context, pairs []Pair, file string, nw *NewSecret) ([]Key, error)

CopyValues writes several values into a new SOPS file in one encryption: sops needs only the recipients of the file's creation rule, nothing is decrypted, so no age identity of the destination is needed. An absent file starts as the Secret nw names (an empty document when nil), a plaintext Secret skeleton is filled; an encrypted file is refused. Every path is checked against the creation rule before a value is read. It answers the keys and their lengths.

func (*Ops) Fingerprints 

func (o *Ops) Fingerprints(ctx context.Context, r Ref) ([]Print, error)

Fingerprints are the keyed fingerprints of what r names, of the one value in o.Encode when an encoding is set.

func (*Ops) Handover added in v0.109.0 

func (o *Ops) Handover(ctx context.Context, creds []Credential) (*Handover, error)

Handover reads every credential of creds now, so that a reference that does not answer, a name that is no variable's or a value that is empty or more than one line, which no variable carries, refuses the whole set before anything runs on it.

func (*Ops) Import added in v0.83.0 

func (o *Ops) Import(ctx context.Context, src, dst Ref) (int, error)

Import copies one field of a vault the person reads, outside the shared vault, into a field of the shared vault (creating the item or the field when absent), and answers the value's length. The source is read with the person's session, the destination written as the service account, or as the person in session mode.

func (*Ops) ImportAge added in v0.112.0 

func (o *Ops) ImportAge(ctx context.Context, src Ref, recipient string) (Ref, int, error)

ImportAge imports the age identity of recipient from src into the shared vault's item of that recipient (AgeItemRef) and answers the destination and the stored identity's length. The source is an identity or an identity file's text (comment lines above the AGE-SECRET-KEY-1… line, keys.txt as age-keygen writes it); only the identity whose public key is recipient is stored, and a source holding none is refused before anything is written, so another key never becomes a recipient's identity.

func (*Ops) Recipients added in v0.109.0 

func (o *Ops) Recipients(ctx context.Context, path string) ([]Recipient, error)

Recipients answers, for a directory, every age recipient of the creation rules of the .sops.yaml nearest above it and, for a SOPS file, the file's recipients (its metadata when encrypted, else its creation rule's), each with where its identity is: sops' own sources, an entry of secret.ageIdentities, the shared vault's item per recipient (checked by the vault's item listing, metadata only), or none. No value is read.

func (*Ops) Reveal added in v0.114.0 

func (o *Ops) Reveal(ctx context.Context, file string, paths []string) ([]Field, error)

Reveal answers the leaves of a SOPS file under paths in plaintext: every scalar a path names, or under it. Each one is classified first, and one that looks secret refuses the whole call, named by its path and the reason, never its value.

func (*Ops) RevealTo added in v0.114.0 

func (o *Ops) RevealTo(ctx context.Context, file, path string, dst Ref, write bool) (RevealResult, error)

RevealTo writes the configuration under path of a SOPS file into dst, a path of a plaintext YAML file (created when absent, its other keys kept), and answers the leaves written, which it never prints. Without write it answers what it would write. A destination that holds the same answers unchanged and writes nothing.

func (*Ops) RotateGenerated added in v0.73.0 

func (o *Ops) RotateGenerated(ctx context.Context, ref Ref, files []string, ix *guard.Index, length int, charset string) (Rotation, error)

RotateGenerated replaces a value beekeeper generated: a new one into the shared vault's field first, then into every path of files that carried the old one, matched by fingerprint. Index matches and learns the values.

func (*Ops) RotateIssued added in v0.73.0 

func (o *Ops) RotateIssued(ctx context.Context, ref Ref, files []string, ix *guard.Index) (Rotation, error)

RotateIssued carries a value a third party issued, which the person put into the shared vault's field, into every path of files that carried the field's old value: the one the index fingerprinted.

func (*Ops) RotatePlatform added in v0.73.0 

func (o *Ops) RotatePlatform(ctx context.Context, r PlatformRef, reason string, dryRun bool) (string, error)

RotatePlatform rotates a platform manager credential with the manager's own rotation, run on the host: platformctl reconciles the capability with --rotate, the manager writes the new value into the installation's SOPS files in a pull request, and nothing is decrypted here. dryRun shows the files that hold it instead. It answers platformctl's output, redacted.

func (*Ops) SecretFingerprint added in v0.111.0 

func (o *Ops) SecretFingerprint(ctx context.Context, t KubeTarget) (Print, error)

SecretFingerprint is the keyed fingerprint of one key of a Secret in a kind cluster, read with the admin kubeconfig kind answers: a delivery is checked against Ops.Fingerprints of its source without a value read. Which contexts a caller may read is the caller's to check.

func (*Ops) SecretKeys added in v0.130.0 

func (o *Ops) SecretKeys(ctx context.Context, file string, opt SecretKeysOptions) ([]CaptureResult, error)

SecretKeys writes the values opt.Produce answers into the keys of the Kubernetes Secret in the SOPS file, under stringData, in one sops write. Every check (the file is a Secret or absent with opt.New, the creation rule encrypts each key, no key is taken without opt.Replace) runs before the producer does. It answers each written key's length and keyed fingerprint, never a value.

func (*Ops) Set 

func (o *Ops) Set(ctx context.Context, dst Ref, opt SetOptions) (SetResult, error)

Set generates a value and writes it to the shared vault's field first when one is given, then into the SOPS path, then into a lab's Secret and a consumer's stdin when given, these three in o.Encode. A value without a vault field lives in the SOPS file alone.

func (*Ops) Setup added in v0.83.0 

func (o *Ops) Setup(ctx context.Context, account, tokenFile string) (Setup, error)

Setup creates the shared vault when absent and a service account that reads and writes it, and writes the account's token to tokenFile (0600). It runs op as the person: the caller's own signed-in session, the one thing a service account cannot do. The token goes from op's stdout to the file and nowhere else.

func (*Ops) StoreFields added in v0.125.0 

func (o *Ops) StoreFields(ctx context.Context, vault, item string, fields []ItemField) ([]Stored, error)

StoreFields writes fields into the item titled item of vault in one op call, the item or a field created when absent, and answers each field's reference, length and fingerprint. Every field is checked before any is written: a label or value that is empty, a value or the item over its bound, a vault not the shared one.

func (*Ops) StoreValue added in v0.118.0 

func (o *Ops) StoreValue(ctx context.Context, dst Ref, v string) (Stored, error)

StoreValue writes v into the vault field dst, the item or the field created when absent, and answers the field, the value's length and its fingerprint.

func (*Ops) Unset added in v0.114.0 

func (o *Ops) Unset(ctx context.Context, file string, paths []string, write bool) (UnsetResult, error)

Unset removes paths from a SOPS file with sops unset in beekeeper's process: the file keeps its recipients, sops renews its MAC and lastmodified. A path the file holds no longer is answered absent, so a second run removes nothing; without write nothing is removed. It answers the key names the file keeps, never a value.

func (*Ops) Use added in v0.138.0 

func (o *Ops) Use(ctx context.Context, r Ref, use func(v string) error) error

Use hands the one value r names to use, in this process: the value reaches no output, file or other process. use's error must carry no part of it.

func (*Ops) Writable added in v0.118.0 

func (o *Ops) Writable(dst Ref) error

Writable refuses a field no store could write: outside the shared vault, or with no way into it (ErrVault).

type Pair added in v0.108.0 

type Pair struct {
	Src  Ref
	Path string
}

Pair is one value of a copy into a new file: the reference it is read from and the path it takes there.

func ParsePair added in v0.108.0 

func ParsePair(s string) (Pair, error)

ParsePair reads <ref>=<path>, the path after the last "=": the reference names one value (op://…, k8s://…, file#path), the path is a key of the new file.

type PlatformRef added in v0.73.0 

type PlatformRef struct {
	Installation, Capability, Name string
}

PlatformRef is a credential the platform manager generates: platform://<installation>/<capability>/<name>, the name as the manager's dry run lists its generated secrets.

func ParsePlatformRef added in v0.73.0 

func ParsePlatformRef(s string) (PlatformRef, error)

ParsePlatformRef reads a platform:// reference.

func (PlatformRef) String added in v0.73.0 

func (r PlatformRef) String() string

type Print 

type Print struct {
	Key         string `json:"key"`
	Fingerprint string `json:"fingerprint"`
}

Print is a value's keyed fingerprint.

type Recipient added in v0.109.0 

type Recipient struct {
	// Rule is the creation rule's path_regex, "(every file)" for one
	// without, or the file whose recipients are answered.
	Rule      string `json:"rule"`
	Recipient string `json:"recipient"`
	// Identity is the source of the recipient's identity: sops' own
	// sources, the entry of secret.ageIdentities, the shared vault's item,
	// or [None] with what is missing.
	Identity string `json:"identity"`
}

Recipient is one age recipient of a .sops.yaml creation rule or of a SOPS file, with where its identity is.

func (Recipient) Missing added in v0.109.0 

func (r Recipient) Missing() bool

Missing reports whether no identity decrypts for r.

type Ref 

type Ref struct {
	Op   string
	Kube KubeTarget
	File string
	Path string
}

Ref names a value or a set of values: an op:// field of the shared vault, a key of a Kubernetes Secret as a source (k8s://<context>/ <namespace>/<name>/<key>, Path then one value inside the document the key holds), a SOPS file, or one path in a SOPS file (file#a.b.c, sops:// in front optional).

func ParseRef 

func ParseRef(s string) (Ref, error)

ParseRef reads a reference.

func (Ref) IsKube added in v0.115.0 

func (r Ref) IsKube() bool

IsKube is whether the reference names a key of a Kubernetes Secret.

func (Ref) Single added in v0.111.0 

func (r Ref) Single() bool

Single is whether the reference names one value.

func (Ref) String 

func (r Ref) String() string

String is the reference as a log and an answer name it.

type RevealResult added in v0.114.0 

type RevealResult struct {
	To        string   `json:"to"`
	Paths     []string `json:"paths"`
	Written   bool     `json:"written"`
	Unchanged bool     `json:"unchanged"`
}

RevealResult is what reveal --to answers: the destination, the leaves it carries, and whether it was written or held them already.

type Rotation added in v0.73.0 

type Rotation struct {
	Ref         string    `json:"ref"`
	Fingerprint string    `json:"fingerprint"`
	Carriers    []Carrier `json:"carriers"`
}

Rotation is what rotate answers: the rotated reference, the new value's fingerprint and the SOPS paths that carry it now.

type Runner 

type Runner func(ctx context.Context, dir string, env []string, stdin io.Reader, name string, args ...string) ([]byte, error)

Runner runs a credential tool in dir with stdin, its environment plus env, and returns its stdout. Its error must carry nothing the tool printed but a redacted first line.

type SecretApplier added in v0.81.0 

type SecretApplier func(ctx context.Context, kubeconfig []byte, t KubeTarget, value []byte) error

SecretApplier writes value into one key of a Secret in the cluster a kubeconfig reaches, the Secret's other keys kept.

type SecretKeysOptions added in v0.130.0 

type SecretKeysOptions struct {
	// Keys are the Secret's keys the values may take, in the order
	// answered; a key the producer answers no value for stays as it is.
	Keys []string
	// New is the Secret an absent file starts as; nil refuses an absent
	// file.
	New *NewSecret
	// Replace overwrites keys the Secret holds already; without it such a
	// key refuses before the producer runs.
	Replace bool
	// Produce makes the values, each under one of Keys. It runs once,
	// after every check passed: a credential handed out once is not spent
	// on a call that could not store it.
	Produce func(context.Context) (map[string]string, error)
}

SecretKeysOptions are the Secret a set of produced values goes into.

type SecretReader added in v0.111.0 

type SecretReader func(ctx context.Context, kubeconfig []byte, t KubeTarget) ([]byte, error)

SecretReader reads one key of a Secret in the cluster a kubeconfig reaches.

type SetOptions added in v0.95.0 

type SetOptions struct {
	Length   int
	Charset  string
	Vault    Ref
	Secret   *KubeTarget
	Consumer []string
	Stdin    Stdin
	// New is the Secret a file absent so far starts as, its name and
	// namespace; nil starts an empty document.
	New *NewSecret
}

SetOptions are what set draws and where the value goes besides the SOPS path: the shared vault's field first, a lab's Secret and a consumer's stdin after it. Each is optional; the value never leaves the process otherwise.

type SetResult added in v0.95.0 

type SetResult struct {
	Key         string `json:"key"`
	Fingerprint string `json:"fingerprint"`
	Code        int    `json:"code,omitempty"`
	Output      string `json:"output,omitempty"`
}

SetResult is what set answers: the value's fingerprint and, with a consumer, its exit code and its output with the value redacted.

type Setup added in v0.83.0 

type Setup struct {
	Vault          string `json:"vault"`
	VaultID        string `json:"vaultId"`
	VaultCreated   bool   `json:"vaultCreated"`
	ServiceAccount string `json:"serviceAccount"`
	TokenFile      string `json:"tokenFile"`
	TokenBytes     int    `json:"tokenBytes"`
}

Setup is what Ops.Setup did: the shared vault, whether it created it, the service account and the length of its token, never the token.

type SigninCause added in v0.108.0 

type SigninCause int

SigninCause is why a sign-in failed, as the keeper tells it from the command's error and the credential store's state when the command ran. 

const (
	// SigninUnknown is a failure with no known pattern.
	SigninUnknown SigninCause = iota
	// SigninRejected is a password 1Password rejected while the credential
	// store answered: the entry the command reads is wrong or rotated.
	SigninRejected
	// SigninStoreLocked is a credential store that was locked.
	SigninStoreLocked
	// SigninStoreAbsent is a session bus with no credential store on it.
	SigninStoreAbsent
	// SigninStore is a credential store the command could not read, by the
	// command's own words.
	SigninStore
	// SigninNetwork is a network that did not reach 1Password.
	SigninNetwork
	// SigninTimeout is a command that did not finish within its bound.
	SigninTimeout
	// SigninCommand is a command that could not run at all.
	SigninCommand
)

func ClassifySignin added in v0.108.0 

func ClassifySignin(err error, store StoreState) SigninCause

ClassifySignin tells why a sign-in failed: from err, the command's failure, and store, the credential store's state when it ran. A store that was locked or absent is the cause whatever the command said: a helper that read no password reports what 1Password said to the empty one. A rejection counts with the store unlocked, or unknown.

func (SigninCause) Rejected added in v0.108.0 

func (c SigninCause) Rejected() bool

Rejected reports whether the cause is one for the person: a rejection that no retry mends.

func (SigninCause) String added in v0.108.0 

func (c SigninCause) String() string

type Stdin added in v0.96.0 

type Stdin struct {
	Template string
	Field    string
}

Stdin shapes what a consumer reads: the value alone, or with Field set, the JSON object Template with the value at Field (garage json-api's request, for one).

func (Stdin) Check added in v0.96.0 

func (s Stdin) Check() error

Check refuses a template that is no JSON object or already holds Field.

type Store added in v0.98.0 

type Store struct {
	// Read prints the secret of the entry appended as its last argument.
	Read []string
	// Search prints the names of the entries matching the term appended as
	// its last argument, one per line, never a value.
	Search []string
}

Store is the person's own credential store, reached through the person's own commands: beekeeper never handles the store's password, and the store shows whatever unlock prompt it shows.

type StoreState added in v0.108.0 

type StoreState int

StoreState is the state of the person's credential store on the session bus (the freedesktop Secret Service: KeePassXC, GNOME Keyring, KWallet), as CredentialStore reads it. 

const (
	// StoreUnknown is a store the keeper cannot ask: no session bus, or a
	// probe that failed.
	StoreUnknown StoreState = iota
	// StoreAbsent is a session bus nobody serves the Secret Service on:
	// the store's program is not up, or the store is no Secret Service.
	StoreAbsent
	// StoreLocked is a Secret Service whose every collection is locked.
	StoreLocked
	// StoreReady is a Secret Service with an unlocked collection.
	StoreReady
)

func CredentialStore added in v0.108.0 

func CredentialStore(ctx context.Context) (StoreState, error)

CredentialStore asks the session bus for the state of the person's credential store, without starting one: absent while nobody serves the Secret Service, locked while every collection is, ready with an unlocked collection. Unknown, with the error, where the bus cannot be asked.

func (StoreState) String added in v0.108.0 

func (s StoreState) String() string

type Stored added in v0.118.0 

type Stored struct {
	Ref         string `json:"ref"`
	Bytes       int    `json:"bytes"`
	Fingerprint string `json:"fingerprint"`
}

Stored is what a store wrote: the field, the value's length and its keyed fingerprint, never the value.

type Storer added in v0.118.0 

type Storer func(ctx context.Context, env, ref, value string) (Stored, error)

Storer writes value into the vault field ref with the session env (OP_SESSION_<id>=<token>) and answers what it wrote.

type UnsetResult added in v0.114.0 

type UnsetResult struct {
	File    string   `json:"file"`
	Removed []string `json:"removed"`
	Absent  []string `json:"absent"`
	Kept    []string `json:"kept"`
	Written bool     `json:"written"`
}

UnsetResult is what unset answers: the paths removed (or, in a dry run, to remove), those the file holds no longer, and the key names it keeps.

type VaultRequest added in v0.91.0 

type VaultRequest struct {
	Op    string `json:"op"`
	Name  string `json:"name,omitempty"`
	Token string `json:"token,omitempty"`
	// Ref and Value are a store's field and what it gets.
	Ref   string `json:"ref,omitempty"`
	Value string `json:"value,omitempty"`
	// Item and Fields are a store-item's item (op://<vault>/<item>) and
	// the fields it gets, in one op call.
	Item   string      `json:"item,omitempty"`
	Fields []ItemField `json:"fields,omitempty"`
}

VaultRequest is one ask of the keeper's socket.

type VaultState added in v0.91.0 

type VaultState struct {
	Unlocked bool      `json:"unlocked"`
	Since    time.Time `json:"since,omitzero"`
	Until    time.Time `json:"until,omitzero"`
	// Error is why the last sign-in failed for good, after its retries.
	Error string `json:"error,omitempty"`
	// Retrying is what the running sign-in waits on or retries after, and
	// when it looks again; empty once it unlocked or failed for good.
	Retrying string `json:"retrying,omitempty"`
	// Dropped is why op stopped taking the last session, at DroppedAt;
	// empty once a sign-in unlocked again.
	Dropped   string    `json:"dropped,omitempty"`
	DroppedAt time.Time `json:"droppedAt,omitzero"`
	// Stored is what a store wrote, Fields what a store-item wrote.
	Stored *Stored  `json:"stored,omitempty"`
	Fields []Stored `json:"fields,omitempty"`
}

VaultState is the keeper's answer.

func AskVault added in v0.91.0 

func AskVault(path string, req VaultRequest) (VaultState, error)

AskVault sends req to the keeper at path and returns its state. The listener must be this very binary, run as this user (Peer): a session goes to beekeeper's broker and nowhere else.

func ReadState added in v0.93.0 

func ReadState(path string) (VaultState, error)

ReadState reads the broker's vault state; locked when the file is absent.

type VaultWait added in v0.91.0 

type VaultWait struct {
	Who   string    `json:"who"`
	Ref   string    `json:"ref"`
	Since time.Time `json:"since"`
}

VaultWait is one call that waits on the person's unlock.

func ReadWaits added in v0.91.0 

func ReadWaits(path string) ([]VaultWait, error)

ReadWaits reads the waiting calls; none when the file is absent.

type Verdict 

type Verdict struct {
	Key   string `json:"key"`
	State string `json:"state"`
}

Verdict is compare's answer for one key.

Source Files

View all Source files

Directories

Path Synopsis
Package secrettest is a fake sops and op for the tests of beekeeper secret: its "encryption" is base64 under a sops metadata block, so a test sees a plaintext value on disk as one and secret takes the file for a sops file, and its vault is a map.
 Package secrettest is a fake sops and op for the tests of beekeeper secret: its "encryption" is base64 under a sops metadata block, so a test sees a plaintext value on disk as one and secret takes the file for a sops file, and its vault is a map.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.