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¶

Неоткриваемо удостоверение е типът удостоверение по подразбиране, създаден, когато потребителят регистрира своя Nitrokey в система за удостоверяване, която поддържа FIDO2/WebAuthn. Системата за удостоверяване съхранява дръжката на ключа, докато частният ключ остава на сигурно място в Nitrokey. Тази конфигурация не използва място за съхранение в Nitrokey и зависи от системата за удостоверяване, която предоставя ключовата дръжка по време на влизане. ПИН кодът на FIDO2 контролира достъпа до Nitrokey и оторизира всички операции, свързани с частни ключове.

Discoverable Credentials¶

Откриваемото удостоверение се съхранява директно в Nitrokey, като включва цялата информация за удостоверението и метаданните, необходими за удостоверяване. Това позволява пълномощното да бъде намерено автоматично от системата за удостоверяване, без да се предоставя външна ключова дръжка, и дава възможност за удостоверяване без потребителско име. Откриваемите удостоверения са защитени с ПИН код FIDO2, който оторизира използването им и гарантира, че само упълномощеният потребител има достъп до тях. Всяко удостоверение обикновено заема няколкостотин байта от защитеното хранилище. Общият брой на удостоверенията зависи от модела на Nitrokey и версията на фърмуера, като обикновено е между 25 и 100 записа.

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

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.
Когато бъдете попитани за пътя до файла, приемете опцията по подразбиране (~/.ssh/id_ed25519_sk) или изберете потребителско име, например id_ed25519_sk_gitlab.
Ако клавишът Nitrokey мига, потвърдете операцията, като го докоснете.
В крайна сметка ще бъдат създадени следните файлове. Имената на файловете може да се различават, ако сте посочили потребителско име при генерирането на ключа.

~/.ssh/id_ed25519_sk → дръжка на частния ключ (съхранява се на сигурно място в Nitrokey)

~/.ssh/id_ed25519_sk.pub → файл с публичен ключ

Adding Your Public Key¶

След като двойката SSH ключове е генерирана, публичният ключ трябва да бъде добавен към услугата или сървъра, до който искате да получите достъп.

Display your public key:

cat ~/.ssh/id_ed25519_sk.pub

Примерен изход (не използвайте този ключ):

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

Копирайте резултата и го добавете към настройките на SSH ключа на вашия акаунт.

See GitLab or GitHub for detailed steps.

За да разрешите отдалечен достъп до SSH сървъра, добавете публичния си ключ във файла ~/.ssh/authorized_keys на потребителския си акаунт на SSH сървъра.