summaryrefslogtreecommitdiff
path: root/secrets/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'secrets/README.md')
-rw-r--r--secrets/README.md15
1 files changed, 13 insertions, 2 deletions
diff --git a/secrets/README.md b/secrets/README.md
index a6ae932..5e98f3f 100644
--- a/secrets/README.md
+++ b/secrets/README.md
@@ -26,7 +26,7 @@ szecret list
| `mv <name> <bucket>` | Move a secret to another bucket; never copies |
| `mv --phone <name> <bucket>` | The same, for a secret this machine can't read: an admin elsewhere (`SZECRET_PHONE_COMMAND`) rewraps its file key |
| `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`) |
+| `list` | The secrets this machine reads, by bucket, with who reads each and anything wrong (`--all`, `--keys`, `--json`, `--names`) |
| `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 |
@@ -59,6 +59,16 @@ buckets/<bucket>/
`~/.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.
+- **`list`** at a terminal shows each bucket this machine reads: its
+ readers by name, its secrets in columns, any problem its file names and
+ headers show (a pending rekey, a file that isn't age, one encrypted to a
+ different number of keys) with the command that fixes it, and a summary.
+ Readers are named by the comment above their key in `recipients`; admins by
+ a `# <name>` line directly above their key in `SZECRET_ADMINS_COMMAND`'s
+ output (older szecret ignores such lines). No key is shown without
+ `--keys` or `--json`. Piped, it prints bare names one a line, and
+ `--names` prints `<bucket>/<name>`: both are read by scripts and stay as
+ they are.
- **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
@@ -174,7 +184,8 @@ For testing or custom setups, these environment variables override default paths
| `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) |
+| `SZECRET_ADMINS_COMMAND` | Prints the admins' public keys, one a line, each optionally named by a `# <name>` line above it | (none: nothing is encrypted to a bucket) |
+| `SZECRET_FORCE_TTY` | `list` prints its terminal view even when piped; a number sets the width | (none) |
* 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.