diff options
Diffstat (limited to 'secrets/README.md')
| -rw-r--r-- | secrets/README.md | 78 |
1 files changed, 53 insertions, 25 deletions
diff --git a/secrets/README.md b/secrets/README.md index 293b747..d4860eb 100644 --- a/secrets/README.md +++ b/secrets/README.md @@ -19,15 +19,49 @@ szecret list | Command | Description | |---------|-------------| -| `get <name>` | Retrieve and decrypt a secret | -| `put <name>` | Store a secret (reads from stdin) | -| `list` | List all secrets in the store | -| `ready` | Check if private key is configured | -| `ensure` | Ensure private key is configured (interactive) | -| `rotate` | Generate a new key and re-encrypt the global store | -| `create-local <name> <dir>` | Create a localized secret store | -| `put-local <file>` | Encrypt to a local store | -| `get-local <file>` | Decrypt from a local store | +| `get <name>`, `get <bucket>/<name>` | Decrypt a secret. A plain name searches every bucket and the old store | +| `has <name>` | Succeed quietly if this machine can read it; decrypts nothing | +| `put <bucket>/<name>` | Encrypt stdin to the bucket's readers and the admins | +| `put <name>` | The same, in `admin-only` (a name still in the old store is rewritten there) | +| `mv <name> <bucket>` | Move a secret to another bucket; never copies | +| `rekey <bucket>` | Re-encrypt a bucket to its readers now; adding a reader needs a yes or `--add-ok` | +| `list` | The secrets this machine reads (`--names`, `--all`) | +| `check [--all]` | Check that the buckets this machine reads (or every bucket) are whole | +| `enrol [--tpm\|--se]` | Make this machine's identity and print its public key | +| `ready` | Check there is a store and an identity | +| `ensure` | Ensure the old private key is configured (interactive) | +| `create-local <name> <dir>` | Create a localized secret store (the old kind) | +| `put-local <file>` | Encrypt to a local store or a repository bucket | +| `get-local <file>` | Decrypt from a local store or a repository bucket | + +## Buckets + +A bucket is a directory of secrets that all have one set of readers, defined +by its readers, not by a workload: a secret is in exactly one bucket, and when +another host needs it, it moves to a bucket that has every reader who needs it. +The design, and who reads which bucket, are cloud-setup's +(`docs/proposal-secret-roles.md`, `szecret/hosts`); szecret knows no host. + +``` +buckets/<bucket>/ + recipients # age public keys, one a line, a comment above each naming its reader + .szecret # kind=bucket, and the full set its files were last encrypted to + <name>.age +``` + +- **The admins**, printed by the command in `SZECRET_ADMINS_COMMAND`, are added + to every encryption. With none, nothing is encrypted. +- **`put` refuses** when the recipients or the admins differ from the set in + `.szecret`, so a forgotten rekey can't leave a removed reader reading new + values. Only `rekey` writes that set. +- **This machine's identity** is `SZECRET_IDENTITY`, or + `~/.local/share/szecret/identity`, made by `enrol` and never copied off; its + public key is in `identity.pub` beside it. Decrypting passes it and the old + key together while both are here. +- **Names** are `[A-Za-z0-9][A-Za-z0-9._-]*`, buckets lowercase, and a name is + unique across every bucket and the old store. +- age 1.3 or later is needed to encrypt (it encrypts to `age1tag1` hardware + keys itself). ## Local Stores @@ -64,16 +98,18 @@ The commands automatically read the store name from the `.szecret` metadata file ### Where the store lives -These scripts carry no secrets. The global store is a directory of `.age` -files plus `id.pub`, the public key they are encrypted to, kept in a checkout -of its own. szecret looks for it in this order: +These scripts carry no secrets. The buckets are found at `$SZECRET_BUCKETS`, +else `~/.local/share/szecret/buckets`. The old global store, which empties as +its secrets move into buckets, is a directory of `.age` files plus `id.pub`, +the public key they are encrypted to, kept in a checkout of its own. szecret +looks for it in this order: 1. `$SZECRET_STORE` and `$SZECRET_PUBLIC_KEY`, if set. 2. `~/.local/share/szecret/store` and `~/.local/share/szecret/id.pub`, beside the private keys. Normally symlinks into the checkout that holds the store. -With neither, every command stops with setup instructions, and `ready` -fails silently. +With no buckets and no old store, every command but `enrol` stops with setup +instructions, and `ready` fails silently. ### Initial Setup @@ -93,17 +129,6 @@ mv private "${HOME}/.local/share/szecret/${pubkey}" szecret ensure ``` -### Rotating the Global Key - -```bash -# Re-encrypt all secrets with a new age key -szecret rotate -``` - -This updates `id.pub` and every file in the store. When complete, commit -those changes in the checkout that holds the store, and update the private key -backup in 1Password. - ## Migration Guide ### Migrating Local Stores (pre-2026) @@ -146,6 +171,9 @@ For testing or custom setups, these environment variables override default paths | `SZECRET_PUBLIC_KEY` | Public key path | `~/.local/share/szecret/id.pub` | | `SZECRET_PRIVATE_KEY` | Single private key file (full override) | (none) | | `SZECRET_PRIVATE_KEY_DIR` | Directory containing private keys (named by their public key) | `~/.local/share/szecret` | +| `SZECRET_BUCKETS` | Buckets directory | `~/.local/share/szecret/buckets` | +| `SZECRET_IDENTITY` | This machine's identity (its public key in `<path>.pub`) | `~/.local/share/szecret/identity` | +| `SZECRET_ADMINS_COMMAND` | Prints the admins' public keys, one a line | (none: nothing is encrypted to a bucket) | * Private keys are stored in `~/.local/share/szecret/` (or `$SZECRET_PRIVATE_KEY_DIR`), with each file named after its public key (e.g. `age1...`). * `id.pub` indicates which public key is current. |
