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¶

Una credencial no detectable es el tipo de credencial predeterminado que se crea cuando el usuario registra su Nitrokey en un sistema de autenticación compatible con FIDO2/WebAuthn. El sistema de autenticación almacena el manejador de la clave, mientras que la clave privada permanece segura dentro de la Nitrokey. Esta configuración no utiliza espacio de almacenamiento en la Nitrokey y depende del sistema de autenticación para proporcionar el identificador de la clave durante el inicio de sesión. El PIN FIDO2 controla el acceso a la Nitrokey y autoriza todas las operaciones relacionadas con las claves privadas.

Discoverable Credentials¶

Una credencial detectable se almacena directamente en la Nitrokey, incluyendo toda la información de la credencial y los metadatos necesarios para la autenticación. Esto permite que el sistema de autenticación encuentre automáticamente la credencial sin necesidad de proporcionar una clave externa y permite la autenticación sin nombre de usuario. Las credenciales detectables están protegidas por el PIN FIDO2, que autoriza su uso y garantiza que sólo el usuario autorizado pueda acceder a ellas. Cada credencial suele ocupar unos cientos de bytes de almacenamiento seguro. El número total de credenciales depende del modelo de Nitrokey y de la versión del firmware, normalmente entre 25 y 100 entradas.

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

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.
Cuando se le pida una ruta de archivo, acepte la opción por defecto (~/.ssh/id_ed25519_sk) o elija un nombre personalizado como id_ed25519_sk_gitlab.
Si la Nitrokey parpadea, confirme la operación tocándola.
Finalmente se crearán los siguientes archivos. Los nombres de los archivos pueden diferir si especificó un nombre personalizado al generar la clave.

~/.ssh/id_ed25519_sk → Mango de la clave privada (almacenada de forma segura en la Nitrokey).

~/.ssh/id_ed25519_sk.pub → archivo de clave pública

Adding Your Public Key¶

Una vez generado su par de claves SSH, debe añadir la clave pública al servicio o servidor al que desea acceder.

Display your public key:

cat ~/.ssh/id_ed25519_sk.pub

Ejemplo de salida (no utilice esta tecla):

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

Copie el resultado y añádalo a la configuración de la clave SSH de su cuenta.

See GitLab or GitHub for detailed steps.

Para habilitar el acceso remoto SSH al servidor, añada su clave pública al archivo ~/.ssh/authorized_keys de su cuenta de usuario en el servidor SSH.