SSH Authentication with FIDO2

Compatible Nitrokeys
3A/C/Mini	Passkey	HSM 2	Pro 2	FIDO2	Storage 2	Start	U2F
✓ active	✓ active	⨯ inactive	⨯ inactive	✓ active	⨯ inactive	⨯ inactive	⨯ inactive

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

En icke-avslöjbar referens är den standardreferenstyp som skapas när användaren registrerar sin Nitrokey med ett autentiseringssystem som stöder FIDO2/WebAuthn. Autentiseringssystemet lagrar nyckelhandtaget, medan den privata nyckeln ligger kvar på ett säkert sätt inuti Nitrokey. Den här konfigurationen använder inget lagringsutrymme på Nitrokey och är beroende av att autentiseringssystemet tillhandahåller nyckelhandtaget under inloggningen. FIDO2 PIN kontrollerar åtkomst till Nitrokey och auktoriserar alla operationer som involverar privata nycklar.

Discoverable Credentials

En identifierbar referens lagras direkt på Nitrokey, inklusive all referensinformation och metadata som krävs för autentisering. Detta gör att autentiseringsuppgifterna kan hittas automatiskt av autentiseringssystemet utan att tillhandahålla ett externt nyckelhandtag och möjliggör autentisering utan användarnamn. Upptäckta referenser skyddas av FIDO2 PIN, som auktoriserar deras användning och säkerställer att endast den auktoriserade användaren kan komma åt dem. Varje referenser upptar vanligtvis några hundra byte av säker lagring. Det totala antalet referenser beror på Nitrokey-modellen och firmware-versionen, vanligtvis mellan 25 och 100 poster.

Generating SSH Key

1. Insert the Nitrokey into your computer.

2. 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"
   

   Observera

   Discoverable credentials can later be listed and imported on another system with:

   ssh-keygen -K
   

3. 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.

4. När du ombeds ange en filsökväg kan du acceptera standardalternativet (~/.ssh/id_ed25519_sk) eller välja ett eget namn, t.ex. id_ed25519_sk_gitlab.

5. Om Nitrokey blinkar ska du bekräfta åtgärden genom att röra vid den.

6. Så småningom kommer följande filer att skapas. Filnamnen kan skilja sig åt om du angav ett anpassat namn när du genererade nyckeln.

   ~/.ssh/id_ed25519_sk → handtag till den privata nyckeln (lagras säkert på Nitrokey)

   ~/.ssh/id_ed25519_sk.pub → fil med offentlig nyckel

   

Adding Your Public Key

När SSH-nyckelparet har skapats måste den publika nyckeln läggas till i den tjänst eller server som du vill komma åt.

1. Display your public key:

   cat ~/.ssh/id_ed25519_sk.pub
   

   Exempel på utdata (använd inte den här tangenten):

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

2. Kopiera utdata och lägg till den i ditt kontos SSH-nyckelinställningar.

   See GitLab or GitHub for detailed steps.

   För att aktivera SSH-fjärråtkomst till server lägger du till din publika nyckel i filen ~/.ssh/authorized_keys för ditt användarkonto på SSH-servern.