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 ikke-opdagelig legitimation er den standardlegitimationstype, der oprettes, når brugeren registrerer sin Nitrokey med et godkendelsessystem, der understøtter FIDO2/WebAuthn. Godkendelsessystemet gemmer nøglehåndtaget, mens den private nøgle forbliver sikkert inde i Nitrokey. Denne konfiguration bruger ingen lagerplads på Nitrokey og er afhængig af, at godkendelsessystemet leverer nøglehåndtaget under login. FIDO2-PIN’en kontrollerer adgangen til Nitrokey og autoriserer alle operationer, der involverer private nøgler.

Discoverable Credentials

En legitimation, der kan findes, gemmes direkte på Nitrokey, inklusive alle legitimationsoplysninger og metadata, der kræves til godkendelse. Dette gør det muligt for legitimationsoplysningerne at blive fundet automatisk af godkendelsessystemet uden at give et eksternt nøglehåndtag og muliggør godkendelse uden brugernavn. Legitimationsoplysninger, der kan findes, er beskyttet af FIDO2 PIN, som autoriserer deres brug og sikrer, at kun den autoriserede bruger kan få adgang til dem. Hver legitimation optager typisk et par hundrede bytes sikker lagring. Det samlede antal legitimationsoplysninger afhænger af Nitrokey-modellen og firmwareversionen, typisk mellem 25 og 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"
   

   Bemærk

   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 bliver bedt om at angive en filsti, kan du acceptere standardindstillingen (~/.ssh/id_ed25519_sk) eller vælge et brugerdefineret navn som id_ed25519_sk_gitlab.

5. Hvis Nitrokey blinker, skal du bekræfte handlingen ved at røre ved den.

6. Til sidst vil følgende filer blive oprettet. Filnavnene kan variere, hvis du har angivet et brugerdefineret navn, da du genererede nøglen.

   ~/.ssh/id_ed25519_sk → håndtag til den private nøgle (gemt sikkert på Nitrokey)

   ~/.ssh/id_ed25519_sk.pub → offentlig nøglefil

   

Adding Your Public Key

Når dit SSH-nøglepar er genereret, skal den offentlige nøgle føjes til den tjeneste eller server, du vil have adgang til.

1. Display your public key:

   cat ~/.ssh/id_ed25519_sk.pub
   

   Eksempel på output (brug ikke denne tast):

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

2. Kopier outputtet, og tilføj det til din kontos SSH-nøgleindstillinger.

   See GitLab or GitHub for detailed steps.

   For at aktivere SSH-fjernserveradgang skal du tilføje din offentlige nøgle til filen ~/.ssh/authorized_keys for din brugerkonto på SSH-serveren.