mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-30 07:37:36 +00:00
ArjenandJohnathan Corgan
7c7722dac9
A node that came back under a new identity left no sign of it in its own log. The ephemeral start that moved fips.key aside warned that a key had been moved, but not whose it was, and a later persistent start that found no key generated one with only an info line. The first visible symptom was a new npub at the node's peers: ACL rejections at a relay, an inbound link from an unknown key, and hosts entries naming an npub that no longer answered, which read as an attack or a network fault one hop away from the cause. Both moved-aside warnings now begin "Node identity changed" and carry previous_npub, the npub the retired key holds, next to npub, the one the start runs as. A persistent start that generates a key while fips.key.unused is present warns the same way, naming that key's npub, its path and how to return to it. That report is made before the new key is written, so a start that cannot save it and falls back to an ephemeral identity reports it too. When only fips.pub names a different npub, the start logs both at info, not as a warning. Every ephemeral start writes fips.pub, so the documented path of installing, setting persistent: true and restarting always finds a different npub there, and the daemon cannot tell that from the public key of a persistent key that was lost. A node's first persistent start, with neither trace present, still generates silently. The npub of a retired or set-aside key, and the one fips.pub names, are read only from a small regular file, opened once without following a symlink and without blocking, since a FIFO in its place could block the start; anything else is named "unreadable". Text in fips.pub is logged only if it decodes as an npub, so an nsec put there by mistake never reaches the log. The persistent start still generates over a key set aside rather than refusing: ephemeral nodes before 0.5.2 wrote a throwaway key to fips.key on every start, so many upgraded nodes hold a fips.key.unused that is not worth keeping. The how-to and the tutorial now say that switching an ephemeral node to persistent logs the new npub, and warns when a fips.key.unused is present.
342 lines
13 KiB
Markdown
342 lines
13 KiB
Markdown
# Make Your Node's Identity Persistent
|
|
|
|
After completing
|
|
[join-the-test-mesh](join-the-test-mesh.md), your daemon is
|
|
connected to the public test mesh — but its identity is
|
|
ephemeral. Every restart generates a fresh Nostr keypair, so the
|
|
npub the rest of the world would use to reach you changes every
|
|
time. This tutorial walks through pinning your node to a stable
|
|
keypair, locating it on disk, and protecting it.
|
|
|
|
The whole exercise should take about ten minutes.
|
|
|
|
## What you'll build
|
|
|
|
```text
|
|
┌─────────────────────────────────────────┐
|
|
│ /etc/fips/fips.yaml │
|
|
│ node: │
|
|
│ identity: │
|
|
│ persistent: true ← this flag │
|
|
└────────────────┬────────────────────────┘
|
|
│ daemon reads on start
|
|
▼
|
|
┌─────────────────────────────────────────┐
|
|
│ /etc/fips/fips.key 0600 root:root │
|
|
│ /etc/fips/fips.pub 0644 root:root │
|
|
└─────────────────────────────────────────┘
|
|
your stable nsec / npub
|
|
```
|
|
|
|
The diagram shows the Linux layout. On macOS the same three files
|
|
live under `/usr/local/etc/fips/`; read
|
|
[Where these files live](#where-these-files-live) before running any
|
|
command below.
|
|
|
|
After this tutorial your node will have:
|
|
|
|
- A keypair on disk that the daemon reuses across restarts.
|
|
- An npub you can hand to other operators so they can add you to
|
|
their `peers:` list once and have the entry keep working.
|
|
- A clear understanding of which file holds the secret and how
|
|
to keep it that way.
|
|
|
|
## Where these files live
|
|
|
|
Every path in this tutorial is written in its Linux form. macOS and
|
|
FreeBSD install config and keys under `/usr/local/etc/fips/` instead
|
|
of `/etc/fips/`, so on those platforms substitute as you go:
|
|
|
|
| Linux / other Unix | macOS / FreeBSD |
|
|
| --- | --- |
|
|
| `/etc/fips/fips.yaml` | `/usr/local/etc/fips/fips.yaml` |
|
|
| `/etc/fips/fips.key` | `/usr/local/etc/fips/fips.key` |
|
|
| `/etc/fips/fips.pub` | `/usr/local/etc/fips/fips.pub` |
|
|
|
|
`fipsctl keygen` writes to `/usr/local/etc/fips/` by default on
|
|
macOS. The daemon still probes `/etc/fips/fips.yaml` as a fallback,
|
|
so an existing install is not broken by an upgrade, but the macOS
|
|
packaging only installs files under `/usr/local/etc/fips/`. If a
|
|
macOS host already carries key files at the old `/etc/fips/` path,
|
|
the daemon uses the old key and warns rather than minting a new
|
|
identity; the migration recipe is in the
|
|
[how-to guide](../how-to/persistent-identity.md).
|
|
|
|
## Why a stable identity matters
|
|
|
|
In FIPS your Nostr keypair *is* your node's identity in the most
|
|
literal sense. Several things derive from it:
|
|
|
|
- Your `fd97:...` mesh address — derived from the public key.
|
|
- Your `<npub>.fips` DNS name — the npub itself with `.fips`
|
|
appended.
|
|
- Every authenticated connection — Noise IK at the mesh layer,
|
|
XK at the session layer, both prove you hold the matching
|
|
secret key.
|
|
|
|
> **A keypair, briefly.** Nostr identities are secp256k1
|
|
> keypairs. The private half is the `nsec` (a bech32-encoded
|
|
> secret key); the public half is the `npub` (a bech32-encoded
|
|
> public key). The daemon needs the `nsec` to sign messages and
|
|
> complete handshakes; the rest of the world only sees the
|
|
> `npub` and uses it as your address.
|
|
|
|
The daemon supports two ways of holding that keypair:
|
|
|
|
> **Ephemeral vs. persistent.**
|
|
>
|
|
> - *Ephemeral* (the default): the daemon mints a brand-new
|
|
> keypair every time it starts, kept only in memory. No
|
|
> long-term secret is ever written to disk; nothing on your
|
|
> machine ties one run to the next; the npub your daemon
|
|
> presents to the network is fresh on every restart. This is
|
|
> the safe-by-default posture — your node has no persistent
|
|
> identity unless you explicitly ask for one.
|
|
> - *Persistent*: the daemon reads (or, on first start,
|
|
> generates and writes) a keypair stored at
|
|
> `/etc/fips/fips.key` (`/usr/local/etc/fips/fips.key` on
|
|
> macOS). The npub stays the same across
|
|
> restarts, reboots, and reinstalls as long as that file is
|
|
> preserved. You take on the cost of protecting an on-disk
|
|
> secret in exchange for being addressable by a stable name.
|
|
|
|
Persistent identity is a deliberate trade. You give up the
|
|
ephemeral default's privacy posture — once your npub is stable,
|
|
every connection your node makes is correlatable across time —
|
|
and you take on a real secret-management responsibility. In
|
|
return you get two things you can't get any other way:
|
|
|
|
1. **Other operators can reference you by npub.** In
|
|
[join-the-test-mesh](join-the-test-mesh.md) you added
|
|
`test-us01` to your `peers:` list by its npub. That entry
|
|
only works because `test-us01`'s npub doesn't change. If
|
|
anyone is going to reach you the same way, your npub has to
|
|
be just as stable.
|
|
2. **Services on your node get a fixed address.** The
|
|
[host-a-service](host-a-service.md) tutorial walks through
|
|
running an HTTP server addressable as
|
|
`<your-npub>.fips`. Clients reach the service by that
|
|
name; if your npub changes on every restart, every
|
|
client's address book breaks.
|
|
|
|
Both of these are good reasons. Neither is automatic — if your
|
|
node is purely a *client*, reaching out to others without
|
|
hosting anything itself, you may legitimately want to stay on
|
|
the ephemeral default. The rest of this tutorial assumes you've
|
|
decided you want a stable identity.
|
|
|
|
## Step 1: Note your current ephemeral npub
|
|
|
|
Before changing anything, capture the npub the daemon is using
|
|
right now so you can compare against it after the switch.
|
|
|
|
```sh
|
|
sudo fipsctl show status | grep '"npub"'
|
|
```
|
|
|
|
You'll see one line like:
|
|
|
|
```text
|
|
"npub": "npub1abc...xyz"
|
|
```
|
|
|
|
Make a note of it. We expect this to change.
|
|
|
|
## Step 2: Enable persistent identity in the config
|
|
|
|
Open `/etc/fips/fips.yaml` (`/usr/local/etc/fips/fips.yaml` on
|
|
macOS) and find the `node:` block. The shipped default has the
|
|
relevant fragment commented out; make it look like this:
|
|
|
|
```yaml
|
|
node:
|
|
identity:
|
|
persistent: true
|
|
```
|
|
|
|
Save the file. That is the only configuration change.
|
|
|
|
The daemon's behavior on the next restart:
|
|
|
|
- If `/etc/fips/fips.key` already exists, load it and use that
|
|
identity.
|
|
- If it does not exist, generate a fresh keypair, write it to
|
|
`/etc/fips/fips.{key,pub}` with the correct file modes, and
|
|
use that.
|
|
|
|
The daemon derives the key directory from whichever config file it
|
|
loaded, so on macOS both files land in `/usr/local/etc/fips/`.
|
|
|
|
## Step 3: Restart the daemon
|
|
|
|
```sh
|
|
sudo systemctl restart fips
|
|
sudo systemctl status fips
|
|
```
|
|
|
|
Status should show `active (running)` within a couple of
|
|
seconds. Confirm the new identity is in use:
|
|
|
|
```sh
|
|
sudo fipsctl show status | grep '"npub"'
|
|
```
|
|
|
|
The npub should be **different** from the one in Step 1 — the
|
|
daemon discarded the old in-memory ephemeral keypair and minted
|
|
a new one which it has now persisted to disk. From here forward
|
|
this is *your* npub. The journal records the change with both
|
|
npubs; if a `fips.key.unused` is present, the start warns
|
|
instead and names the npub that key holds.
|
|
|
|
## Step 4: Locate the keypair on disk
|
|
|
|
The daemon wrote two files:
|
|
|
|
```sh
|
|
sudo ls -l /etc/fips/fips.key /etc/fips/fips.pub
|
|
```
|
|
|
|
On macOS, list `/usr/local/etc/fips/fips.key` and
|
|
`/usr/local/etc/fips/fips.pub` instead.
|
|
|
|
Expect:
|
|
|
|
```text
|
|
-rw------- 1 root root ... fips.key
|
|
-rw-r--r-- 1 root root ... fips.pub
|
|
```
|
|
|
|
The public file is safe to share — it is your address:
|
|
|
|
```sh
|
|
sudo cat /etc/fips/fips.pub
|
|
```
|
|
|
|
This must match the `npub` reported by `sudo fipsctl show
|
|
status`. Hand this string to anyone you want to be reachable
|
|
from; they paste it into their own `peers:` block as the `npub:`
|
|
field.
|
|
|
|
The private file is the secret. **Do not** `cat` or paste its
|
|
contents anywhere — there is no reason to see it, and any line
|
|
of shell history or screen capture that contains it has captured
|
|
the secret.
|
|
|
|
## Step 5: Verify it survives a restart
|
|
|
|
Restart once more to confirm the daemon is reading `fips.key`
|
|
rather than re-generating it:
|
|
|
|
```sh
|
|
sudo systemctl restart fips
|
|
sudo fipsctl show status | grep '"npub"'
|
|
```
|
|
|
|
The npub should match Step 3 exactly. If it does not, the daemon
|
|
was unable to read `fips.key` (most likely a permission problem)
|
|
— see [Troubleshooting](#troubleshooting).
|
|
|
|
## Step 6: Protect the nsec
|
|
|
|
`fips.key` is the only thing standing between you and someone
|
|
else impersonating your node. The daemon ships it with the right
|
|
permissions; the operator's job is to keep them that way.
|
|
|
|
What that means in practice:
|
|
|
|
- **Do not loosen the file mode.** `0600` (read/write for owner
|
|
only — here `root`) is correct; `chmod 0644` to "fix" a
|
|
permission error puts the secret on display to every account
|
|
on the host.
|
|
- **Do not commit it to source control.** If you maintain
|
|
configuration in a Git repo, exclude `fips.key`; if you use
|
|
ansible-vault or a similar mechanism, encrypt it. `fips.pub`
|
|
may be checked in freely.
|
|
- **Do not paste it into chat or email.** Operators sometimes
|
|
share config snippets to demonstrate a setup; redact the
|
|
contents of `fips.key` to a placeholder before doing so.
|
|
- **Back it up the way you back up an SSH host key.** Treat the
|
|
file (or its contents) the same way you would treat
|
|
`/etc/ssh/ssh_host_ed25519_key`: encrypted, offline, available
|
|
to recover the *same* identity if the host disappears.
|
|
|
|
There is no in-protocol "key change" message in FIPS. If
|
|
`fips.key` is lost, the npub is lost — your node will come back
|
|
up with a new identity and every downstream reference to the
|
|
old one will be stale.
|
|
|
|
## What you've learned
|
|
|
|
- **Identity = keypair.** Every FIPS node is a Nostr keypair;
|
|
the npub is its address, the nsec is its credential.
|
|
- **The flag.** `node.identity.persistent: true` in
|
|
`/etc/fips/fips.yaml` is the difference between ephemeral and
|
|
persistent identity.
|
|
- **Where it lives.** `/etc/fips/fips.key` and
|
|
`/etc/fips/fips.pub`, mode `0600` and `0644`, owned
|
|
`root:root`; under `/usr/local/etc/fips/` on macOS.
|
|
- **What to share.** `fips.pub` is public; `fips.key` is not.
|
|
- **What it buys you.** A npub other operators can add to their
|
|
`peers:` list once, and that addresses the services your node
|
|
will eventually run.
|
|
|
|
## Troubleshooting
|
|
|
|
If the post-restart npub does not match `fips.pub`:
|
|
|
|
- **Check file permissions.**
|
|
`sudo ls -l /etc/fips/fips.key`, or
|
|
`sudo ls -l /usr/local/etc/fips/fips.key` on macOS. If the mode
|
|
is not `0600` or the owner is not `root:root`, the daemon may
|
|
have refused to read it. Restore with
|
|
`sudo chmod 0600 /etc/fips/fips.key && sudo chown root:root
|
|
/etc/fips/fips.key`, substituting the macOS path where it
|
|
applies.
|
|
- **Check the journal.** `sudo journalctl -u fips -n 100` after
|
|
the restart will show one of:
|
|
- `Loaded persistent identity from key file path=...` — good.
|
|
- `Generated persistent identity, saved to key file ...` —
|
|
also good, but only expected on the first start after the
|
|
flag flip.
|
|
- `Using ephemeral identity (new keypair each start)` — the
|
|
config flag was not picked up; re-check the indentation of
|
|
the `persistent: true` line.
|
|
|
|
If you see `Generated persistent identity...` on every start,
|
|
the file is being written but not read on subsequent starts;
|
|
this is almost always the same permission/path issue.
|
|
|
|
## What's next
|
|
|
|
- **Resolve peer addresses via Nostr.**
|
|
[resolve-peers-via-nostr](resolve-peers-via-nostr.md) walks
|
|
through the smallest useful step toward Nostr-mediated
|
|
discovery: keep your peer entry, drop its hard-coded address,
|
|
and let the daemon look up the current endpoint from public
|
|
Nostr relays. The first of three tutorials covering Nostr
|
|
discovery; advertising your own node and open ambient
|
|
discovery come next.
|
|
|
|
- **Reach services on other mesh nodes.**
|
|
[reach-mesh-services](reach-mesh-services.md) drives `nc`,
|
|
`traceroute6`, `curl`, and `ssh` at peers by `.fips` name and
|
|
shows that the FIPS data plane is just IPv6 from an
|
|
application's point of view.
|
|
|
|
- **Host a service of your own.**
|
|
[host-a-service](host-a-service.md) walks through bringing up
|
|
an HTTP server addressable as `<your-npub>.fips`, bound to
|
|
`fips0` so the exposure is mesh-only, behind the mesh
|
|
firewall.
|
|
|
|
For the alternative provisioning paths — minting a keypair with
|
|
`fipsctl keygen` before the daemon ever starts, or importing an
|
|
existing Nostr `nsec` — and the key-rotation procedure, see the
|
|
operator-style recipe at
|
|
[../how-to/persistent-identity.md](../how-to/persistent-identity.md).
|
|
|
|
For the full identity model:
|
|
|
|
- [../design/fips-architecture.md](../design/fips-architecture.md)
|
|
— how npubs become `NodeAddr`s and IPv6 ULAs.
|