SSH Authentication with FIDO2¶

Compatible Nitrokeys
✓ active	✓ active	⨯ inactive	⨯ inactive	✓ active	⨯ inactive	⨯ inactive	⨯ inactive

Compatible Nitrokeys

SSH (Secure Shell) is a network protocol used to securely access and manage remote systems such as servers or code repositories. It uses cryptographic key pairs for authentication, allowing passwordless logins with strong security.

With a Nitrokey, the private SSH key is generated and stored directly on the device, so it never leaves the hardware. Each login requires you to touch the Nitrokey, adding a simple physical confirmation that protects against unauthorized access. For example, when connecting to a server, GitLab, or GitHub.

Non-Discoverable Credentials¶

Een niet-ontdekbaar kenmerk is het standaard kenmerktype dat wordt aangemaakt wanneer de gebruiker zijn Nitrokey registreert bij een verificatiesysteem dat FIDO2/WebAuthn ondersteunt. Het verificatiesysteem slaat het sleutelhandvat op, terwijl de privésleutel veilig in de Nitrokey blijft. Deze configuratie gebruikt geen opslagruimte op de Nitrokey en is afhankelijk van het verificatiesysteem om de sleutelhendel te leveren tijdens het inloggen. De FIDO2 PIN controleert de toegang tot de Nitrokey en autoriseert alle handelingen met privésleutels.

Discoverable Credentials¶

Een detecteerbare referentie wordt direct op de Nitrokey opgeslagen, inclusief alle referentie-informatie en metagegevens die nodig zijn voor verificatie. Hierdoor kan de referentie automatisch door het verificatiesysteem worden gevonden zonder dat er een externe sleutel hoeft te worden opgegeven en is verificatie zonder gebruikersnaam mogelijk. Ontdekbare referenties worden beschermd door de FIDO2 PIN, die het gebruik ervan autoriseert en ervoor zorgt dat alleen de geautoriseerde gebruiker er toegang toe heeft. Elke referentie neemt normaal gesproken een paar honderd bytes aan beveiligde opslagruimte in beslag. Het totale aantal referenties hangt af van het model Nitrokey en de firmwareversie, meestal tussen 25 en 100 vermeldingen.

Generating SSH Key¶

Insert the Nitrokey into your computer.
Open a terminal and create your SSH key. Replace "your_comment" with a label to identify it (e.g., “Nitrokey GitLab”). By default, the key is created as a non-discoverable credential. In this case, a local key handle is stored in ~/.ssh/ while the private key remains on the Nitrokey. This means the key is tied to the system where it was generated, since the local key handle file is required for authentication. Use the -O resident option to create a discoverable credential. In this case, the credential is stored on the Nitrokey, making it portable and usable across different systems without copying any local files.

Non-discoverable credential:
```
ssh-keygen -t ed25519-sk -C "your_comment"
```
Discoverable credential:
```
ssh-keygen -t ed25519-sk -O resident -C "your_comment"
```
Notitie

Discoverable credentials can later be listed and imported on another system with:
```
ssh-keygen -K
```
During key generation, you may also be asked to set a passphrase. This passphrase encrypts the local key handle stored in ~/.ssh/ (not the private key on the Nitrokey, which always stays securely inside the device). The passphrase is different from the FIDO2 device PIN. The PIN protects the physical key itself, while the passphrase protects your local SSH public key file. We recommend to use a passphrase to protect non-discoverable keys only.
Wanneer om een bestandspad wordt gevraagd, accepteer dan de standaardoptie (~/.ssh/id_ed25519_sk) of kies een aangepaste naam zoals id_ed25519_sk_gitlab.
Als de Nitrokey knippert, bevestig dan de handeling door hem aan te raken.
Uiteindelijk worden de volgende bestanden aangemaakt. De bestandsnamen kunnen verschillen als je een aangepaste naam hebt opgegeven bij het genereren van de sleutel.

~/.ssh/id_ed25519_sk → handvat voor de privésleutel (veilig opgeslagen op de Nitrokey)

~/.ssh/id_ed25519_sk.pub → openbaar sleutelbestand

Adding Your Public Key¶

Zodra je SSH sleutelpaar is gegenereerd, moet de publieke sleutel worden toegevoegd aan de service of server die je wilt benaderen.

Display your public key:

cat ~/.ssh/id_ed25519_sk.pub

Voorbeelduitvoer (gebruik deze toets niet):

sk-ssh-ed25519@openssh.com AAAAGnNrLXNzaC1lZDI1NTE5QG7wZW4zc2guY29tAAAAILeZl6r07HV4i1rK07OfLqD3J4IzX2q0lB6Ok0pdxoG5AAAABHNzaDo= your_comment

Kopieer de uitvoer en voeg deze toe aan de SSH-sleutelinstellingen van je account.

See GitLab or GitHub for detailed steps.

Om SSH remote server toegang in te schakelen, voeg je je publieke sleutel toe aan het bestand ~/.ssh/authorized_keys van je gebruikersaccount op de SSH-server.