# szecret Secret management using [age](https://github.com/FiloSottile/age) encryption. ## Quick Start ```bash # Store a secret echo "my-api-key" | szecret put api-key # Retrieve a secret szecret get api-key # List all secrets szecret list ``` ## Commands | Command | Description | |---------|-------------| | `get `, `get /` | Decrypt a secret. A plain name searches every bucket and the old store | | `has ` | Succeed quietly if this machine can read it; decrypts nothing | | `put /` | Encrypt stdin to the bucket's readers and the admins | | `put ` | The same, in `admin-only` (a name still in the old store is rewritten there) | | `mv ` | Move a secret to another bucket; never copies | | `mv --phone ` | The same, for a secret this machine can't read: an admin elsewhere (`SZECRET_PHONE_COMMAND`) rewraps its file key | | `rekey ` | Re-encrypt a bucket to its readers now; adding a reader needs a yes or `--add-ok` | | `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 | | `ensure` | Ensure the old private key is configured (interactive) | | `create-local / ` | Create a localized secret store, its key in ``, which this machine must read | | `create-local ` | The same for an existing store, or on a machine with no buckets | | `put-local ` | Encrypt to a local store or a repository bucket | | `get-local ` | 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// 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 .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. - **`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 `# ` 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 `/`: 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 keys itself). ## Local Stores Local stores allow you to keep encrypted secrets outside the global store, useful for project-specific secrets that live alongside the code. ### Creating a Local Store ```bash # Initialize a local store in a directory szecret create-local web-hosts/myproject /path/to/project/secrets/ # This creates: # - A key, local-key-myproject, in the bucket web-hosts: that bucket's # readers read the store (on a machine with no buckets, # `create-local myproject ` puts it in the global store) # - A metadata file at /path/to/project/secrets/.szecret containing: # store=myproject # pubkey=age1... ``` The metadata includes the public key for verification, preventing accidental use of the wrong store. ### Using a Local Store ```bash # Encrypt a secret echo "db-password" | szecret put-local /path/to/project/secrets/db.age # Decrypt a secret szecret get-local /path/to/project/secrets/db.age ``` The commands automatically read the store name from the `.szecret` metadata file in the directory. ## Setup ### Where the store lives 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 no buckets and no old store, every command but `enrol` stops with setup instructions, and `ready` fails silently. ### Initial Setup ```bash # Generate a new keypair (file must be named after its public key) age-keygen -o private pubkey="$(age-keygen -y private)" mkdir -p ~/.local/share/szecret/store echo "${pubkey}" > ~/.local/share/szecret/id.pub mv private "${HOME}/.local/share/szecret/${pubkey}" ``` ### On a New Machine ```bash # The ensure command will prompt for your private key szecret ensure ``` ## Migration Guide ### Migrating Local Stores (pre-2026) If you created local stores before the metadata system was introduced, run `create-local` again with the directory - it will detect the existing key and just add the metadata: ```bash szecret create-local myapp /path/to/secrets/ # Output: Added metadata for existing store 'myapp' ``` **Before (old syntax):** ```bash szecret create-local myapp echo "secret" | szecret put-local myapp /path/to/secrets/password.age szecret get-local myapp /path/to/secrets/password.age ``` **After (new syntax):** ```bash # One-time migration szecret create-local myapp /path/to/secrets/ # Now use simplified commands echo "secret" | szecret put-local /path/to/secrets/password.age szecret get-local /path/to/secrets/password.age ``` **For automated scripts:** The old `get-local ` syntax still works but emits a deprecation warning suggesting the migration command. ## Environment Variables For testing or custom setups, these environment variables override default paths: | Variable | Description | Default | |----------|-------------|---------| | `SZECRET_STORE` | Global store directory | `~/.local/share/szecret/store` | | `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 `.pub`) | `~/.local/share/szecret/identity` | | `SZECRET_ADMINS_COMMAND` | Prints the admins' public keys, one a line, each optionally named by a `# ` 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. ## Testing ```bash # Run all tests ./test/run.sh # Run specific tests ./test/run.sh local create-local ``` See [test/README.md](test/README.md) for more details.