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¶

Un justificatif non découvrable est le type de justificatif par défaut créé lorsque l’utilisateur enregistre sa Nitrokey auprès d’un système d’authentification prenant en charge FIDO2/WebAuthn. Le système d’authentification stocke la poignée de la clé, tandis que la clé privée reste en sécurité à l’intérieur de la Nitrokey. Cette configuration n’utilise pas d’espace de stockage sur la Nitrokey et dépend du système d’authentification pour fournir l’identifiant de la clé lors de la connexion. Le PIN de Nitrokey FIDO2 contrôle l’accès à la Nitrokey et autorise toutes les opérations impliquant des clés privées.

Discoverable Credentials¶

Un justificatif découvrable est stocké directement sur la Nitrokey, y compris toutes les informations sur le justificatif et les métadonnées nécessaires à l’authentification. Cela permet au système d’authentification de trouver automatiquement le justificatif sans avoir à fournir une clé externe et permet une authentification sans nom d’utilisateur. Les références découvrables sont protégées par le code PIN FIDO2, qui autorise leur utilisation et garantit que seul l’utilisateur autorisé peut y accéder. Chaque identifiant occupe généralement quelques centaines d’octets de stockage sécurisé. Le nombre total d’identifiants dépend du modèle de Nitrokey et de la version du micrologiciel, généralement entre 25 et 100 entrées.

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"
```
Note

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.
Lorsque l’on vous demande un chemin d’accès, acceptez l’option par défaut (~/.ssh/id_ed25519_sk) ou choisissez un nom personnalisé comme id_ed25519_sk_gitlab.
Si la Nitrokey clignote, confirmez l’opération en la touchant.
Les fichiers suivants seront éventuellement créés. Les noms des fichiers peuvent être différents si vous avez spécifié un nom personnalisé lors de la génération de la clé.

~/.ssh/id_ed25519_sk → poignée de la clé privée (stockée en toute sécurité sur la Nitrokey)

~/.ssh/id_ed25519_sk.pub → fichier de clés publiques

Adding Your Public Key¶

Une fois la paire de clés SSH générée, la clé publique doit être ajoutée au service ou au serveur auquel vous souhaitez accéder.

Display your public key:

cat ~/.ssh/id_ed25519_sk.pub

Exemple de sortie (ne pas utiliser cette touche): :

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

Copiez le résultat et ajoutez-le aux paramètres de la clé SSH de votre compte.

See GitLab or GitHub for detailed steps.

Pour permettre l’accès au serveur distant SSH, ajoutez votre clé publique au fichier ~/.ssh/authorized_keys de votre compte d’utilisateur sur le serveur SSH.