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¶

Una credenziale non scopribile è il tipo di credenziale predefinito creato quando l’utente registra il proprio Nitrokey con un sistema di autenticazione che supporta Nitrokey FIDO2/WebAuthn. Il sistema di autenticazione memorizza l’handle della chiave, mentre la chiave privata rimane al sicuro all’interno di Nitrokey. Questa configurazione non utilizza spazio di archiviazione su Nitrokey e dipende dal sistema di autenticazione per fornire l’handle della chiave durante il login. Il PIN Nitrokey FIDO2 controlla l’accesso alla Nitrokey e autorizza tutte le operazioni che coinvolgono le chiavi private.

Discoverable Credentials¶

Una credenziale rilevabile viene memorizzata direttamente su Nitrokey, includendo tutte le informazioni sulla credenziale e i metadati necessari per l’autenticazione. Questo permette alla credenziale di essere trovata automaticamente dal sistema di autenticazione senza fornire una chiave esterna e consente l’autenticazione senza nome utente. Le credenziali rilevabili sono protette dal PIN FIDO2, che ne autorizza l’uso e garantisce che solo l’utente autorizzato possa accedervi. Ogni credenziale occupa in genere poche centinaia di byte di memoria sicura. Il numero totale di credenziali dipende dal modello di Nitrokey e dalla versione del firmware, in genere è compreso tra 25 e 100 voci.

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

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.
Quando viene richiesto il percorso del file, accettare l’opzione predefinita (~/.ssh/id_ed25519_sk) o scegliere un nome personalizzato come id_ed25519_sk_gitlab.
Se il Nitrokey lampeggia, confermare l’operazione toccandolo.
Alla fine verranno creati i seguenti file. I nomi dei file possono essere diversi se si è specificato un nome personalizzato durante la generazione della chiave.

~/.ssh/id_ed25519_sk → handle della chiave privata (memorizzata in modo sicuro su Nitrokey)

~/.ssh/id_ed25519_sk.pub → file della chiave pubblica

Adding Your Public Key¶

Una volta generata la coppia di chiavi SSH, la chiave pubblica deve essere aggiunta al servizio o al server a cui si vuole accedere.

Display your public key:

cat ~/.ssh/id_ed25519_sk.pub

Esempio di uscita (non utilizzare questo tasto):

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

Copiate il risultato e aggiungetelo alle impostazioni della chiave SSH del vostro account.

See GitLab or GitHub for detailed steps.

Per abilitare l’accesso remoto al server SSH, aggiungere la propria chiave pubblica al file ~/.ssh/authorized_keys del proprio account utente sul server SSH.