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¶

A non-discoverable credential is the default credential type created when the user registers their Nitrokey with an authentication system that supports FIDO2/WebAuthn. The authentication system stores the key handle, while the private key remains securely inside the Nitrokey. This configuration uses no storage space on the Nitrokey and depends on the authentication system to supply the key handle during login. The FIDO2 PIN controls access to the Nitrokey and authorizes all operations involving private keys.

Discoverable Credentials¶

Zistiteľný mandát je uložený priamo na Nitrokey vrátane všetkých informácií o mandáte a metadát potrebných na overenie. To umožňuje, aby autentifikačný systém automaticky našiel poverenie bez poskytnutia externej kľúčenky a umožňuje autentifikáciu bez používateľského mena. Discoverable credentials sú chránené kódom FIDO2 PIN, ktorý autorizuje ich použitie a zabezpečuje, že k nim má prístup len oprávnený používateľ. Každé poverenie zvyčajne zaberá niekoľko stoviek bajtov zabezpečenej pamäte. Celkový počet poverení závisí od modelu a verzie firmvéru Nitrokey, zvyčajne je to 25 až 100 záznamov.

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"
```
Poznámka

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.
Keď budete požiadaní o cestu k súboru, prijmite predvolenú možnosť (~/.ssh/id_ed25519_sk) alebo vyberte vlastný názov, napríklad id_ed25519_sk_gitlab.
Ak tlačidlo Nitrokey bliká, potvrďte operáciu jeho dotykom.
Nakoniec sa vytvoria tieto súbory. Názvy súborov sa môžu líšiť, ak ste pri generovaní kľúča zadali vlastný názov.

~/.ssh/id_ed25519_sk → prístup k súkromnému kľúču (bezpečne uložený na Nitrokey)

~/.ssh/id_ed25519_sk.pub → súbor s verejným kľúčom

Adding Your Public Key¶

Po vygenerovaní páru kľúčov SSH je potrebné pridať verejný kľúč k službe alebo serveru, ku ktorému chcete získať prístup.

Display your public key:

cat ~/.ssh/id_ed25519_sk.pub

Príklad výstupu (nepoužívajte tento kľúč):

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

Skopírujte výstup a pridajte ho do nastavení kľúča SSH svojho konta.

See GitLab or GitHub for detailed steps.

Ak chcete povoliť vzdialený prístup k serveru SSH, pridajte svoj verejný kľúč do súboru ~/.ssh/authorized_keys svojho používateľského účtu na serveri SSH.