mirror of
https://github.com/jmcorgan/fips.git
synced 2026-10-06 11:38:24 +00:00
Johnathan Corgan
5a79d3fc5e
Brings up the two release lines' work: the maint harness and guard fixes, the documentation corrections, master's probe, onion and epoch fixes, and both rebuilt changelog blocks. Three conflicts. The readme conflicted on the badge pair. Resolved by taking the Rust badge that no longer asserts a version, since rust-toolchain.toml is the only place that states one, and keeping this line's own v0.6.0-dev status badge. The peer machine conflicted, and the resolution is an adaptation rather than a pick. Master deleted PeerMachine.remote_epoch on the grounds that nothing read it, and that reasoning had to be re-derived here because this line's machine is the XX rewrite and shares almost no text with it. It holds. The shadow's only production write is inbound_msg3, which is where XX crystallizes identity, so it is inbound-only exactly as the msg1 write was on the other lines; conn carries the same value written from both legs, complete_handshake on the outbound one and complete_handshake_msg3 on the inbound; the only read is the cutover action payload, whose executor arm binds nothing; and the live consumer reads conn_remote_epoch. So an initiator cutover, which runs on an outbound machine, carried a zeroed epoch here too. One thing differs and needed handling. This line has an `established` constructor the others do not, and it writes the shadow and conn from the same argument, which would have made the field direction-correct. Its only caller is in the test module and its own doc comment calls the machine inert, so it is a seam that is not wired yet rather than a production path, and it does not rescue the field. Its assignment goes with the rest; the parameter stays, because conn still needs the value. The adaptation is folded into this merge rather than left to a follow-on, because master's half of the same change reached peer_actions.rs through a clean auto-merge. Keeping this line's field while accepting that auto-merge would have left the machine emitting a payload field the executor no longer has, which is a break that only the test build shows. The changelog conflicted because both lines had rebuilt their unreleased block. The Breaking section stays at the top untouched; Unreleased now holds the ten entries that are this line's own; and the other two lines' work sits below under 0.5.0 and 0.4.2 headings, neither dated, matching how master already carries 0.4.2. Four entries existed on both sides in branch-adapted form and were merged rather than picked, so each keeps the rework's wording and this line's accuracy: the OpenWrt entry drops its IK reference, the msg1 classifier keeps the promotion-state paragraph, the SessionAck entry keeps the two XX-only exits, and the msg3 epoch entry counts six sites here against master's five.
341 lines
13 KiB
Markdown
341 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. The macOS
|
|
package (`.pkg`) installs config and keys under
|
|
`/usr/local/etc/fips/` instead of `/etc/fips/`, so on macOS
|
|
substitute as you go:
|
|
|
|
| Linux / other Unix | macOS |
|
|
| --- | --- |
|
|
| `/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 XX 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.
|
|
|
|
## 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.
|