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¶

発見不可能なクレデンシャルは、ユーザーが FIDO2/WebAuthn をサポートする認証システムにニトロキーを登録するときに作成されるデフォルトのクレデンシャルタイプである。認証システムはキーハンドルを保存し、秘密鍵はニトロキー内に安全に残ります。この構成では、ニトロキーのストレージ領域を使用せず、ログイン時にキーハンドルを供給する認証システムに依存する。FIDO2 PINは、ニトロキーへのアクセスを制御し、秘密鍵を含むすべての操作を承認する。

Discoverable Credentials¶

発見可能なクレデンシャルは、認証に必要なすべてのクレデンシャル情報とメタデータを含め、ニトロキーに直接格納される。これにより、外部キー・ハンドルを提供することなく、認証システムによってクレデンシャルが自動的に検出され、ユーザ名なしの認証が可能になる。発見可能なクレデンシャルは FIDO2 PIN によって保護され、この PIN はその使用を認可し、認可されたユーザのみがアクセスできるようにする。各クレデンシャルは通常、数百バイトの安全なストレージを占める。クレデンシャルの総数は、ニトロキーのモデルとファームウェアのバージョンに依存し、通常は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 のようなカスタム名を選択する。
ニトロキーが点滅した場合は、ニトロキーをタッチして操作を確認してください。
最終的に以下のファイルが作成される。キーの生成時にカスタム名を指定した場合は、ファイル名が異なる場合があります。

~/.ssh/id_ed25519_sk` → 秘密鍵へのハンドル（ニトロキーに安全に保存されている）

~/.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サーバー上のユーザー・アカウントのファイル``~/.ssh/authorized_keys`` に公開鍵を追加する。