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¶

Ein nicht auffindbarer Berechtigungsnachweis ist der Standardberechtigungstyp, der erstellt wird, wenn der Benutzer seinen Nitrokey bei einem Authentifizierungssystem registriert, das FIDO2/WebAuthn unterstützt. Das Authentifizierungssystem speichert das Schlüsselhandle, während der private Schlüssel sicher im Nitrokey verbleibt. Diese Konfiguration verwendet keinen Speicherplatz auf dem Nitrokey und hängt davon ab, dass das Authentifizierungssystem das Schlüsselhandle bei der Anmeldung bereitstellt. Die FIDO2-PIN steuert den Zugriff auf den Nitrokey und autorisiert alle Vorgänge mit privaten Schlüsseln.

Discoverable Credentials¶

Ein auffindbarer Berechtigungsnachweis wird direkt auf dem Nitrokey gespeichert, einschließlich aller für die Authentifizierung erforderlichen Berechtigungsnachweisinformationen und Metadaten. Dadurch kann der Berechtigungsnachweis automatisch vom Authentifizierungssystem gefunden werden, ohne dass ein externes Schlüsselhandle erforderlich ist, und ermöglicht eine Authentifizierung ohne Benutzernamen. Erkennbare Berechtigungsnachweise sind durch die FIDO2-PIN geschützt, die ihre Verwendung autorisiert und sicherstellt, dass nur der autorisierte Benutzer auf sie zugreifen kann. Jeder Berechtigungsnachweis belegt in der Regel einige hundert Bytes an sicherem Speicherplatz. Die Gesamtzahl der Berechtigungsnachweise hängt vom Nitrokey-Modell und der Firmware-Version ab und liegt normalerweise zwischen 25 und 100 Einträgen.

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

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.
Wenn Sie nach einem Dateipfad gefragt werden, akzeptieren Sie die Standardoption (~/.ssh/id_ed25519_sk) oder wählen Sie einen eigenen Namen wie id_ed25519_sk_gitlab.
Wenn der Nitrokey blinkt, bestätigen Sie den Vorgang, indem Sie ihn berühren.
Schließlich werden die folgenden Dateien erstellt. Die Dateinamen können abweichen, wenn Sie bei der Erstellung des Schlüssels einen eigenen Namen angegeben haben.

~/.ssh/id_ed25519_sk → Handle zum privaten Schlüssel (sicher auf dem Nitrokey gespeichert)

~/.ssh/id_ed25519_sk.pub → Datei mit öffentlichem Schlüssel

Adding Your Public Key¶

Sobald Ihr SSH-Schlüsselpaar erzeugt ist, muss der öffentliche Schlüssel zu dem Dienst oder Server hinzugefügt werden, auf den Sie zugreifen möchten.

Display your public key:

cat ~/.ssh/id_ed25519_sk.pub

Beispielausgabe (diese Taste nicht verwenden):

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

Kopieren Sie die Ausgabe und fügen Sie sie zu den SSH-Schlüsseleinstellungen Ihres Kontos hinzu.

See GitLab or GitHub for detailed steps.

Um den SSH-Fernzugang zum Server zu ermöglichen, fügen Sie Ihren öffentlichen Schlüssel in die Datei ~/.ssh/authorized_keys Ihres Benutzerkontos auf dem SSH-Server ein.