secretsmgr handbook
Editor sign-in

Terms and acronyms

Everything you need to read the rest of this handbook, defined before it is used. Skip what you already know. The words this tool uses in a special sense, like principal and grant, are collected separately in the Glossary at the end, because those need the surrounding chapters to make sense.

Acronyms

ShortLongWhat it means here
APIApplication Programming InterfaceHow one program talks to another. An API key is a credential that identifies a program to some service, and is one of the most common things people keep in a secrets manager.
CI (CI/CD)Continuous Integration (and Continuous Delivery)The automated system that builds, tests, and deploys your code when you push it. It works unattended with no human present, which is exactly why it needs credentials and why it gets an identity of its own here.
CLICommand Line InterfaceThe secretsmgr command you type in a terminal. This tool is a CLI with no graphical interface.
KMSKey Management ServiceA cloud service (AWS KMS, Google Cloud KMS, Azure Key Vault) that holds encryption keys and does encryption and decryption on request, without ever handing the key itself back. Used here as one way to protect your private key.
FIDO2(the standard behind hardware security keys)The open standard your YubiKey or equivalent implements. WebAuthn is the half websites speak; CTAP2 is the half that talks to the device itself. hmac-secret is an optional CTAP2 feature this tool uses to derive an unlocking key that can never leave the device.
HMACHash-based Message Authentication CodeA one-way function that takes a key as well as data. Used here to turn readable secret names into unreadable identifiers that members can still match up.
TLSTransport Layer SecurityThe "s" in https, which protects data while it crosses the network. Worth knowing that in this tool TLS is not what keeps your secrets confidential; they are already encrypted before they are sent.
TTLTime To LiveHow long something stays valid before expiring. Used here for the key cache and for enrollment vouchers.

Background words

TermWhat it means
git, repository, clone, historyGit is the version control system most teams already use. A repository (or repo) is a project's files plus every past version of them. A clone is a complete local copy, including that history, which is why deleting a file from a repository does not remove it from anyone's clone.
upstreamThe real system a credential belongs to: the database, the payment provider, the mail service. "Rotating upstream" means changing the password on that system itself, as opposed to changing what is written down here.
environment variableA named value handed to a program when it starts. The usual way an application receives its configuration and its credentials.
.env fileA plain text file listing environment variables. Convenient, and one of the most common ways secrets escape, because it is so easy to commit one by accident.
stdinStandard input: the channel a program reads when you pipe data into it. Passing a secret this way keeps it out of your shell history and out of the list of running processes, where anyone on the machine could read it.
pipeline, runnerA pipeline is the sequence of automated steps CI performs for you. A runner is the machine that executes them, often a throwaway one created for a single job.
containerA packaged, isolated process, as run by Docker, Podman, or Kubernetes. Server mode ships as one.
plaintext, ciphertextA message before encryption, and the scrambled version after it.
hashA short, fixed-size fingerprint computed from data. The same input always gives the same hash, and you cannot work backwards from the hash to the data. Changing one byte changes the hash completely, which is what makes it useful for detecting tampering.
fingerprintA hash rendered short enough for a human to read aloud and compare. Used here so two people can confirm they are looking at the same key. Worked through in the fingerprints chapter.
workload identity federationA way for a program running in CI or in a cloud to prove what it is to another cloud service, without any stored credential to leak. It is what makes KMS custody possible for machines.
compare-and-swap"Make this change, but only if the thing is still exactly as I last saw it." The rule that stops two people writing at the same moment from losing one another's work.