Secrets, fields and versions
| Term | Meaning |
|---|---|
| Secret | A named collection of fields in a project. Secrets are regional resources (us-west-1) with an ID, an sec_ slug and a resource name. The name is yours and is unique in the project. |
| Field | A name and a value. A secret’s version holds any number of fields, up to 1,000. |
| Version | One immutable snapshot of a secret’s fields, numbered from 1. A version is enabled or destroyed. |
latest |
The highest-numbered enabled version. A secret with no enabled version has no latest, and reading it is 404. |
| Grant | Permission for one EZGH product to read a secret for one of its resources. See Grants. |
A secret’s name is up to 128 characters: letters, digits, _, ., / and -, starting with a
letter or digit, such as prod/db. Description and tags are optional, and you can change them at
any time. Nothing else about a secret changes: to change a value, you write a new version.
Fields
- A field name is up to 256 characters: letters, digits,
_,.and-, starting with a letter or_. Names are case-sensitive. - A value is text (UTF-8) or binary, up to 8 KiB (8,192 bytes) after decoding. An empty value is
allowed. In the API a binary value is
{ "base64": "..." }, and you get it back in the form you wrote it.
Versions
A write creates a version, either as the complete set of fields, or as changes to an existing
version: take version 3 (or latest), set some fields and remove others. Changing one field
this way doesn’t need the writer to read the rest.
- Versions never change. Readers read
latestor pin a number, and an old version stays readable until you destroy it. - Destroying a version erases its values at once and keeps its record, with the state
destroyed. Destroyinglatestmakes the next lower enabled versionlatest. A destroyed version can’t be read again, by anyone; reading it is404witherror.details.reason: "destroyed". - A secret can have up to 100,000 enabled versions. Nothing is destroyed automatically, and you pay for the fields of every enabled version, so destroy versions you no longer need.
- Writes that race for the same version number fail with
409 conflict: run the write again. SendIf-Matchwith the secret’sETagto make a write succeed only if the secret hasn’t changed.
Encryption
Values are encrypted at rest with envelope encryption:
- Every secret has its own data key. Each version’s values are encrypted with a key derived from it, and the data key is stored only in encrypted form, itself encrypted by a key-encryption key.
- Key-encryption keys are rotated every 90 days. Rotation re-encrypts data keys and doesn’t interrupt reads or writes.
- Key-encryption keys are encrypted by a root key that is kept outside the database, in the platform’s secret store.
- Values are never written to logs, error messages or Trails, and API responses that contain
values are marked
Cache-Control: no-store.
You don’t manage keys. Encryption at rest protects stored data: anyone your policies allow to
read a value receives it in clear text over HTTPS, so grant secrets.versions.access carefully.
Deleting secrets and versions
- Destroying a version erases its values immediately.
- Deleting a secret erases every version’s values, its data key, its versions and its grants immediately. It can’t be undone and has no recovery window.
- Deleting a project or your organization erases the secrets it contains within minutes.
Where secrets are read
Two kinds of reader use Secrets:
- Your workloads: applications, CI and the
ezghCLI, calling the API with an API key, a CLI login or a console session. IAM is checked on every request. - EZGH products that you’ve given a grant.
Each read you make of a value is a billed read, and Trails records every read, including the products’. Reads by products through a grant aren’t billed.