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¶

Nezjistitelný pověření je výchozí typ pověření vytvořený při registraci klíče Nitrokey do ověřovacího systému, který podporuje FIDO2/WebAuthn. Ověřovací systém uloží klíčový handle, zatímco soukromý klíč zůstane bezpečně uložen uvnitř klíče Nitrokey. Tato konfigurace nevyužívá žádný úložný prostor v klíči Nitrokey a závisí na autentizačním systému, který při přihlašování poskytne handle klíče. Kód PIN FIDO2 řídí přístup ke klíči Nitrokey a autorizuje všechny operace se soukromými klíči.

Discoverable Credentials¶

Zjistitelné pověření je uloženo přímo na klíči Nitrokey, včetně všech informací o pověření a metadat potřebných k ověření. To umožňuje automatické nalezení pověření autentizačním systémem bez nutnosti zadávat externí handle klíče a umožňuje autentizaci bez uživatelského jména. Zjistitelné pověření je chráněno kódem FIDO2 PIN, který autorizuje jeho použití a zajišťuje, že k němu má přístup pouze oprávněný uživatel. Každé pověření obvykle zabírá několik set bajtů zabezpečeného úložiště. Celkový počet pověření závisí na modelu Nitrokey a verzi firmwaru, obvykle se pohybuje mezi 25 a 100 záznamy.

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.
Při dotazu na cestu k souboru můžete přijmout výchozí možnost (~/.ssh/id_ed25519_sk) nebo zvolit vlastní název, například id_ed25519_sk_gitlab.
Pokud tlačítko Nitrokey bliká, potvrďte operaci dotykem.
Nakonec se vytvoří následující soubory. Pokud jste při generování klíče zadali vlastní název, mohou se názvy souborů lišit.

~/.ssh/id_ed25519_sk → přístup k soukromému klíči (bezpečně uložený na Nitrokey)

~/.ssh/id_ed25519_sk.pub → soubor s veřejným klíčem

Adding Your Public Key¶

Po vygenerování páru klíčů SSH je třeba přidat veřejný klíč ke službě nebo serveru, ke kterému chcete přistupovat.

Display your public key:

cat ~/.ssh/id_ed25519_sk.pub

Příklad výstupu (tento klíč nepoužívejte):

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

Zkopírujte výstup a přidejte jej do nastavení klíče SSH svého účtu.

See GitLab or GitHub for detailed steps.

Chcete-li povolit vzdálený přístup k serveru SSH, přidejte svůj veřejný klíč do souboru ~/.ssh/authorized_keys svého uživatelského účtu na serveru SSH.