summaryrefslogtreecommitdiff
path: root/secrets/README.md
blob: 69fd53c52a9f46f029a4dccacf760e715082ade7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
# 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 <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 |
| `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, 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 <bucket>/<name> <dir>` | Create a localized secret store, its key in `<bucket>`, which this machine must read |
| `create-local <name> <dir>` | The same for an existing store, or on a machine with no buckets |
| `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.
- **`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
  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 <dir>` 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 <store-name> <file>` 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 `<path>.pub`) | `~/.local/share/szecret/identity` |
| `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.

## 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.