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

Ei-tunnisteellinen tunnistetieto on oletusarvoinen tunnistetietotyyppi, joka luodaan, kun käyttäjä rekisteröi Nitrokey-avaimensa FIDO2/WebAuthn-tunnistusjärjestelmää tukevaan tunnistusjärjestelmään. Todennusjärjestelmä tallentaa avainkahvan, kun taas yksityinen avain pysyy turvallisesti Nitrokey-avaimen sisällä. Tämä kokoonpano ei käytä tallennustilaa Nitrokey-avaimessa, ja se on riippuvainen siitä, että todennusjärjestelmä toimittaa avainkahvan kirjautumisen yhteydessä. Nitrokey FIDO2 PIN-koodi valvoo pääsyä Nitrokey-avaimeen ja valtuuttaa kaikki yksityisiä avaimia koskevat toiminnot.

Discoverable Credentials

Löydettävissä oleva valtakirja tallennetaan suoraan Nitrokey-avaimeen, mukaan lukien kaikki valtakirjan tiedot ja todennuksessa tarvittavat metatiedot. Tämän ansiosta todentamisjärjestelmä löytää valtakirjan automaattisesti ilman ulkoisen avaimen kahvaa ja mahdollistaa todennuksen ilman käyttäjätunnusta. Löydettävissä olevat valtakirjat suojataan FIDO2 PIN-koodilla, joka valtuuttaa niiden käytön ja varmistaa, että vain valtuutettu käyttäjä voi käyttää niitä. Kukin tunnistetieto vie tyypillisesti muutaman sata tavua suojattua tallennustilaa. Tunnisteiden kokonaismäärä riippuu Nitrokey-mallista ja laiteohjelmistoversiosta, yleensä 25-100 merkintää.

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"
   

   Muista

   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. Kun sinua pyydetään antamaan tiedostopolku, voit hyväksyä oletusvaihtoehdon (~/.ssh/id_ed25519_sk) tai valita mukautetun nimen, kuten id_ed25519_sk_gitlab.

5. Jos Nitrokey vilkkuu, vahvista toiminto koskettamalla sitä.

6. Lopulta luodaan seuraavat tiedostot. Tiedostojen nimet voivat poiketa toisistaan, jos olet määrittänyt mukautetun nimen avainta luodessasi.

   ~/.ssh/id_ed25519_sk → yksityisen avaimen kahva (tallennettu turvallisesti Nitrokey-avaimeen).

   ~/.ssh/id_ed25519_sk.pub → julkisen avaimen tiedosto

   

Adding Your Public Key

Kun SSH-avainpari on luotu, julkinen avain on lisättävä palveluun tai palvelimeen, jota haluat käyttää.

1. Display your public key:

   cat ~/.ssh/id_ed25519_sk.pub
   

   Esimerkkitulostus (älä käytä tätä näppäintä):

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

2. Kopioi tulos ja lisää se tilisi SSH-avainasetuksiin.

   See GitLab or GitHub for detailed steps.

   Jos haluat ottaa SSH-etäpalvelimen käyttöön, lisää julkinen avaimesi SSH-palvelimen käyttäjätilisi tiedostoon ~/.ssh/authorized_keys.