Give your keys names

Why name a key?

If you keep two or three keys plugged in — or rotate a primary and a backup — they all look alike to the operating system, and the path the OS assigns each one (/dev/hidraw3 today, /dev/hidraw5 tomorrow) shifts on every replug. A name fixes that: "signing-yubikey" always means the same physical key, no matter which port it's in.

This makes the device list easier to read at a glance, and it lets you target a specific key on the command line with --device instead of hunting for the right path.

Two places to keep a name

When you name a key, you choose where the name lives:

On this computer (the default). The name goes in a keys.json file on this computer. Other computers don't see it.
On the key. The name is written into the key's FIDO2 large-blob storage, so every computer running keyroost shows it, with no setup. Saving it asks for the key's FIDO PIN. The name is visible to anyone who has the key: reading it needs no PIN. Only keys with large-blob storage offer this choice.

A name on the key is shown first. A name this computer saved shows only when the key carries none.

Naming a key in the app

In the keyroost desktop app, select the key and use the Name this key action next to its title (it reads Rename once the key has a name). Type a name, choose On this computer or On this key, and confirm. For a name on the key, the dialog asks for the key's PIN. Renaming a key whose name is on the key changes it there.

If a key no longer carries the name this computer saw on it, the app says so and offers Write it back, Forget (remove the name from this computer) or Not now.

Naming a key from the command line

keyroostctl name set signing-yubikey                # on this computer
keyroostctl name set signing-yubikey --store key    # on the key (asks for the FIDO PIN)
keyroostctl name list                               # every name, where it lives, what is connected
keyroostctl piv info -d signing-yubikey             # use it
keyroostctl name clear signing-yubikey              # remove it, wherever it is stored

name set NAME names the key, or renames it. A rename keeps the name where it is; --store key moves a name from this computer onto the key. If several keys are plugged in, a terminal shows a numbered list to pick from; in a script, say which one with -d (a serial or a list number), --reader or --path. Any key that reports a serial can be named; Molto2 tokens can't be named yet.
name list shows every name this computer knows, where it lives, and which key is connected. If a key lost its name, the line says how to write it back.
name clear NAME removes a name wherever it is stored (a name on the key needs the key connected and its PIN). -d KEY name clear removes the selected key's name.

Once a key is named, commands that target a single key accept --device signing-yubikey (or -d). --device also takes a serial or the number keyroostctl list shows; prefix name:, serial: or list: to say which you mean. With the shell completions installed, pressing Tab after --device offers the names in this computer's keys.json.

Name rules

A name is 1–64 characters and otherwise free-form: letters of any case or script, digits, spaces and punctuation are all fine — Signing YubiKey, Clé de bureau, backup-2. It is stored exactly as typed. Only control, zero-width and bidi characters are rejected, because those let a name spoof what it displays as. A name read from a key that breaks these rules is not shown, and the key is treated as unnamed. Each name on this computer belongs to one key.

Two keys with the same name

Anyone can write any name onto a key, so two keys can carry the same one. The first key this computer saw with a name keeps it: --device "Work YubiKey" always means that key. Another key carrying the same name shows as Work YubiKey (1234), with the last four characters of its serial. That text is for display only; select the second key by its list number, by serial:…, or from the picker. If only the second key is plugged in, --device "Work YubiKey" says no key by that name is connected and shows Work YubiKey (1234) as the key that carries it.

How keyroost tells keys apart

keyroost recognizes a key by its serial number, not by a port or a slot:

For most keys (SoloKeys, Nitrokey, and similar) the serial is the USB iSerialNumber the key reports to the operating system.
For keys that don't expose a USB serial (such as YubiKeys), keyroost reads the serial from a vendor management applet over the smart-card (CCID) interface instead.

So a named key is recognized the moment it's connected, in any port, and is shown as "not connected" when it's absent. keyroost pairs a card reader with its USB device by where both sit on the USB bus (Linux) or in the Windows device tree, and refuses to fall back to a name-based guess when the evidence is ambiguous, so in a crowded, hard-to-disambiguate set a key may read as not connected rather than being confidently mistaken for its neighbor — deliberately, since a wrong match would send card operations and FIDO operations to two different physical keys.

macOS doesn't report where a device sits. There, and on Windows when the device tree can't be read, keyroost asks each side of the key for the identity it reports (a YubiKey's serial, a Solo 2's ID, a Token2 key's serial) and joins the two only when they match. These reads change nothing on the key. If two keys of the same make are connected and one doesn't answer, it is shown as two entries rather than guessed at.

Some keys report the same serial on every unit (the OnlyKey, for example). keyroost can't tell such units apart, so naming them works as it did before: units that share a name are refused as ambiguous rather than guessed at.

What keyroost stores on this computer

keys.json holds, for each name, the name, where it lives (this computer or the key), and a salted fingerprint of the key: a keyed hash of its serial, not the serial itself. The salt is a random value in keys.salt beside it, made on first use and never shared, so the file shows no serials and two computers' files can't be matched against each other. No secrets, PINs, or credentials are ever part of a name.

A name on the key is recorded here too, the first time this computer sees it. That record is how this computer knows which key carried the name first.

If keys.salt is lost, names saved on this computer no longer match their keys, and name list shows them as unmatched. Clear them with name clear and set them again; putting the old keys.salt back doesn't help.

If this computer can't record a key (for example, the key reports no serial, or keys.json can't be written), keyroost warns once and treats the key as seen here for the first time on every run.

Coming from v0.12 or earlier

Older versions kept plain serials in keys.json. The first time this version reads the file, it converts it to fingerprints. It keeps a backup of the old file until the conversion has succeeded, then removes it, so no serial stays on disk. Your names keep working. If you go back to v0.12, it can't read the converted file and shows your keys unnamed. Don't name or rename a key with v0.12 after upgrading: v0.12 saves a new keys.json over the converted one, and the names in it are lost.

Limits

Windows without administrator rights: keyroost can't reach a key's FIDO side, so it shows only names saved on this computer.
Erasing the key's storage: fido blob clear and a FIDO reset erase a name on the key with everything else. fido blob clear --keep-name keeps it.
Other software: the FIDO2 standard lets a browser or system tool remove large-blob entries that no passkey uses, which would include the name. We haven't seen it happen. A name lives in one place, so if it disappears from the key, the key shows as unnamed until the name is written back: keyroostctl name list prints the one command that restores it, and the app offers Write it back.

The format of the name on the key is published, with test vectors, in PROTOCOL-device-label.md, so other tools can read and write the same name.

Naming works alongside everything else a key can do:

keyroostWhat a security key is keyroostFIDO2 & passkeys keyroostLarge-blob storage keyroostResetting a key safely

From the command line: see Naming your keys on the Command line page.