Keycard

The admin key is what admits devices to a mesh. Normally it is a passphrase-protected file in your home directory. On a Keycard it is a key that never leaves the card — so admitting a device means the card has to be present, and a machine that is compromised while you are asleep cannot admit anyone.

Everything below is what works today, against real hardware. Where the card does less than it appears to, the sentence that says so is included rather than left out.

What it changes — and what it does not
What you need — a reader, or a phone with NFC
Look at the card first — the free command that prevents most of the ways this goes wrong
Initialise a blank card — PIN, PUK, and the phrase to write down
Pair this machine — one of five slots, permanently
Mint the mesh — one command
Admit a phone — and make it an admin too
Day to day — invite, issue, renew, revoke
When something goes wrong — the status words and what they mean

1. What it changes

A mesh admits devices by credential: the admin signs a statement naming one device's keys, and every node checks that signature for itself (ADR-018). The admin key is therefore the thing worth protecting — it is the only key that can add members.

With a file, that key exists in a directory, and anything running as you can read it. With a card, the private half is generated on the card and never leaves it: signing happens on the card, and the most a compromised machine can do is ask it to sign while it is plugged in and unlocked (ADR-022).

What a signature proves, and what it does not. A credential signed by the card proves the admin approved that device. It does not prove anyone was holding a card when it was checked — a signature made last month verifies exactly like one made a second ago. So "the card was used" is a fact about the past, which is the right property for a credential and the wrong one to describe as presence.

The card also does nothing for a mesh that is already yours to read. Membership is what it controls; it is not a second factor on your own traffic.

2. What you need

A Keycard with applet 3.1 or later, and either a USB smartcard reader or a phone with NFC. Both work. This guide uses a reader, because then everything happens in one place.

Reader support is in every build — install shrooms the normal way. What it needs is pcsc-lite on the machine, which most desktop Linux installs already have. Where it is missing, the card commands name the package to install rather than failing obscurely.

sudo apt install pcscd libpcsclite1      # Debian, Ubuntu
sudo dnf install pcsc-lite              # Fedora, RHEL
sudo pacman -S pcsclite                 # Arch

There is no service to start. pcscd is socket-activated: it starts when something asks for a reader and stops when nothing is using one. If a guide anywhere tells you to enable a daemon for this, you do not need it.

The library is opened when you first reach for a card, not linked at build time. A server that has never seen a smartcard runs the same binary, needs none of this, and does not notice it is there.

3. Look at the card first

shrooms keycard status
        applet       3.1
        initialised  true
        key          yes (1839b7db)
        pairing      4 of 5 slots free
        can do       secure-channel, key-management, credentials, ndef, factory-reset

This costs nothing — no pairing slot, no PIN attempt, no password, and nothing on the card changes. Run it first on any card you have not used here. It answers most of the ways setting one up can fail, before anything has been spent.

pairing 0 of 5 slots free is the one to watch for. A card has five pairing slots, they are consumed permanently, and freeing one requires a device that already holds one. Every slot is a device that has ever paired — including failed attempts, and including a machine you have since reinstalled.

A card with no free slots and no paired device left can only be recovered by wiping it completely with shrooms keycard reset, which destroys the key. The way back is the mnemonic, which is why step 4 asks you to write it down.

From a machine that still holds a slot, shrooms keycard free-slots releases every slot except its own.

4. Initialise a blank card

Skip this if status already says initialised true and key yes.

shrooms keycard init

It asks for a PIN (six digits), a PUK (twelve digits, which unblocks a PIN locked by three wrong tries) and a pairing password — press enter for the factory default, which is what a card set up with the Keycard app has.

Then it prints a mnemonic.

That phrase is the only way back to this key. A mesh minted against a key that exists nowhere else dies with the card — a lost card with no phrase means no one can ever admit another device, and the mesh ends when the last credential expires.

It is an ordinary BIP-39 phrase, so it restores into any wallet. Which also means: keeping it beside your crypto backups is keeping your mesh's root key there, with whatever that implies for who can reach it.

shrooms keycard init --restore loads a phrase you already have instead of generating one.

5. Pair this machine

shrooms keycard pair

One of the five slots, once. The pairing is stored beside the admin key and reused from then on. It is not a secret that admits anybody — the PIN is still needed to sign anything — so it lives in your config directory rather than anywhere more ceremonial.

6. Mint the mesh

sudo shrooms init --mesh home --keycard
        Card PIN:
        mesh id     KIXKWYU4JTLL46IFC3IOVTTGOI
        prefix      fd06:507d:b6e0::/48
        authority   02372cd5…
        this device is enrolled

That is the whole thing. It reads the card's public key, makes it the mesh's authority, writes the config, and enrols this machine with a credential the card signs. Add --mesh <label> to put a card-backed mesh on a machine that already has one.

Nothing secret is written. The admin file holds the card's public half — the same value every node checks against anyway.

One admin key, not the usual two. A file authority mints a second key as a paper way back, because losing the file ends the mesh. A card's key already has one — the mnemonic — so a second would be another thing to lose. It also could not itself be a card key, and a single file key in the set would disable the rule that lets a phone complete an invite (ADR-033): an authority is card-backed only if every key in it is.

sudo systemctl enable --now shrooms

Mint each mesh once, on one machine. A card's admin key is derived rather than generated, from an account number the local machine picks — and nothing on the card records which accounts are spent. So running init --keycard from the same card on a second machine picks the same account, derives the same key, and makes a second mesh with the same id.

That pair of meshes is the worst combination available: they have different network keys, so they cannot reach each other — and the same id, so a credential or a revocation issued for one verifies against the other. Neither looks wrong on its own; both print exactly the mesh id, prefix and admin key you would expect.

Mint on one machine and invite the others. Minting refuses when this node already knows the id it would duplicate, and shrooms admin show reports the clash if it has already happened — but neither can see a mesh minted somewhere this node has never been, so the rule is worth keeping rather than relying on the check.

A file authority cannot collide this way; its key is random. This is specific to deriving one from something two machines share.

7. Admit a phone

On the machine with the card:

sudo shrooms invite
        Card PIN:
        Invite valid for 15m0s. On the joining device:
          shrooms join BEGUZ-N4WOX-PYMTR-CYKWT-QBYSX-U
        [QR code]
        Waiting...
        Admitted "phone".

Scan the QR from the phone, or paste the token into Join a mesh. When the phone answers, the card signs its credential and the invite completes. An invite is good for one device and fifteen minutes, and only the node that issued it can answer — so leave the command running until it says Admitted.

Making the phone an admin too

Enrol the same card with the phone over NFC: Settings → Keycard → Set up a card. That takes a second pairing slot, and it is what makes a phone a full admin rather than a member — the key is on the card, not on either device, so both can admit and neither holds anything the other needs.

8. Day to day

shrooms admin show                    # every authority this machine holds
shrooms admin issue --name nas        # enrol a device by its keys, no invite
shrooms admin renew --dry-run         # who is near expiry
shrooms admin renew --all             # reissue before credentials expire
shrooms admin revoke --device HEX      # withdraw one before it expires

Each of these asks for the card's PIN and signs on the card. Credentials last thirty days by default, so renewal is a sweep you run occasionally rather than a ceremony per device — see Invites and membership for how renewal and revocation travel.

9. When something goes wrong

What you see	What it means
`0 of 5 slots free`	every slot is taken. Free them from a device that holds one — `shrooms keycard free-slots`, or the phone's Keycard screen — or wipe the card
`6a84`	the same thing, as the card says it
`6d00` on pairing	the applet has no secure channel; a Cash card is the usual reason. It cannot be paired at all
`6985` reading the key	no PIN verified
`wrong PIN. 2 attempts left`	count them. Three wrong and the card blocks and needs its PUK
`Sharing violation`	something else is holding the reader
`no PC/SC library on this machine`	install `pcsc-lite` — the message names the package for your distribution
`the PC/SC service is not running`	plug the reader in; `pcscd` starts on demand, or `sudo systemctl start pcscd`

shrooms keycard forget drops this machine's pairing — useful before reinstalling, so the slot is not stranded. shrooms keycard readers lists attached readers when there is more than one, for --reader.

shrooms keycard reset is the last resort. It wipes the card completely — key, PIN, PUK and every pairing — and is the only way back from a card with no free slots and no device holding one. The key returns only from the mnemonic. Any mesh minted against that key, whose phrase you do not have, is over.