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¶

Uma credencial não detetável é o tipo de credencial predefinido criado quando o utilizador regista a sua Nitrokey com um sistema de autenticação que suporta FIDO2/WebAuthn. O sistema de autenticação armazena o identificador de chave, enquanto a chave privada permanece segura dentro do Nitrokey. Esta configuração não utiliza espaço de armazenamento no Nitrokey e depende do sistema de autenticação para fornecer o identificador de chave durante o login. O PIN FIDO2 controla o acesso ao Nitrokey e autoriza todas as operações que envolvem chaves privadas.

Discoverable Credentials¶

Uma credencial detetável é armazenada diretamente no Nitrokey, incluindo todas as informações sobre a credencial e os metadados necessários para a autenticação. Isto permite que a credencial seja encontrada automaticamente pelo sistema de autenticação sem fornecer um identificador de chave externo e permite a autenticação sem nome de utilizador. As credenciais detectáveis são protegidas pelo PIN FIDO2, que autoriza a sua utilização e garante que apenas o utilizador autorizado pode aceder às mesmas. Cada credencial normalmente ocupa algumas centenas de bytes de armazenamento seguro. O número total de credenciais depende do modelo Nitrokey e da versão do firmware, normalmente entre 25 e 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.
Quando lhe for pedido um caminho para o ficheiro, aceite a opção predefinida (~/.ssh/id_ed25519_sk) ou escolha um nome personalizado como id_ed25519_sk_gitlab.
Se a Nitrokey ficar intermitente, confirmar a operação tocando-lhe.
Eventualmente, serão criados os seguintes ficheiros. Os nomes dos ficheiros podem ser diferentes se tiver especificado um nome personalizado ao gerar a chave.

~/.ssh/id_ed25519_sk → identificador da chave privada (armazenada de forma segura no Nitrokey)

~/.ssh/id_ed25519_sk.pub → ficheiro de chave pública

Adding Your Public Key¶

Assim que o par de chaves SSH for gerado, a chave pública deve ser adicionada ao serviço ou servidor a que pretende aceder.

Display your public key:

cat ~/.ssh/id_ed25519_sk.pub

Exemplo de saída (não utilizar esta tecla):

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

Copie o resultado e adicione-o às definições de chave SSH da sua conta.

See GitLab or GitHub for detailed steps.

Para ativar o acesso ao servidor remoto SSH, adicione a sua chave pública ao ficheiro ~/.ssh/authorized_keys da sua conta de utilizador no servidor SSH.