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 и зависит от системы аутентификации, которая предоставляет ключ-ключ при входе в систему. PIN-код FIDO2 контролирует доступ к Nitrokey и авторизует все операции с закрытыми ключами.

Discoverable Credentials¶

Обнаруживаемый мандат хранится непосредственно на Nitrokey, включая всю информацию о мандате и метаданные, необходимые для аутентификации. Это позволяет системе аутентификации автоматически находить учетную запись без предоставления внешнего ключа и обеспечивает аутентификацию без использования имени пользователя. Обнаруживаемые учетные данные защищены FIDO2 PIN-кодом, который авторизует их использование и гарантирует, что доступ к ним может получить только авторизованный пользователь. Каждая учетная запись обычно занимает несколько сотен байт в защищенном хранилище. Общее количество учетных данных зависит от модели 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"
```
Примечание

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-сервере.