summaryrefslogtreecommitdiff
path: root/secrets/README.md
blob: a6ae93273eb09eddf3b105557674f3eb0689155a (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
# 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 (`--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

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 myproject /path/to/project/secrets/

# This creates:
# - A key in the global store (local-key-myproject)
# - 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 | (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.

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