Add documentation on SSH Authentication with FIDO2

source/components/nitrokeys/features/fido2/ssh.rst

@@ -0,0 +1,67 @@
+SSH Authentication with FIDO2
+=============================
+
+.. product-table:: nk3 passkey fido2
+
+SSH (Secure Shell) is a network protocol used to securely access and manage remote systems such as servers or code repositories (e.g. GitLab, GitHub). 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.
+
+Generating SSH Key
+------------------
+
+1. Insert the Nitrokey into your computer.
+
+2. 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 a non-resident key, meaning a local key handle is stored in ``~/.ssh/`` while the private key remains securely on the Nitrokey.  
+   Use the ``-O resident`` option if you want the key to be portable across systems.
+
+   .. code-block:: shell-session
+
+      ssh-keygen -t ed25519-sk -C "your_comment"
+
+   or to create a resident key
+
+   .. code-block:: shell-session
+
+      ssh-keygen -t ed25519-sk -O resident -C "your_comment"
+
+   .. note::
+
+      Resident keys can later be listed and imported on another system with:
+
+      .. code-block:: shell-session
+
+         ssh-keygen -K
+
+
+3. 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-resident keys only.
+
+4. When asked for a file path, accept the default option (``~/.ssh/id_ed25519_sk``) or choose a custom name like ``id_ed25519_sk_gitlab``.
+
+5. If the Nitrokey blinks, confirm the operation by touching it.
+
+Eventually the following files will be created. The file names may differ if you specified a custom name when generating the key.
+
+   ``~/.ssh/id_ed25519_sk`` → handle to the private key (stored securely on the Nitrokey)
+
+   ``~/.ssh/id_ed25519_sk.pub`` → public key file
+
+.. figure:: images/ssh/terminal.png
+   :alt: img0
+
+
+Adding Your Public Key
+----------------------
+
+Once your SSH key pair is generated, the public key must be added to the service or server you want to access.
+
+1. Display your public key:
+
+   .. code-block:: shell-session
+
+      cat ~/.ssh/id_ed25519_sk.pub
+
+   Example output (do not use this key)::
+
+      [email protected] AAAAGnNrLXNzaC1lZDI1NTE5QG7wZW4zc2guY29tAAAAILeZl6r07HV4i1rK07OfLqD3J4IzX2q0lB6Ok0pdxoG5AAAABHNzaDo= your_comment
+
+2. Copy the output and add it to your account’s SSH key settings. See `GitLab <https://docs.gitlab.com/user/ssh/#add-an-ssh-key-to-your-gitlab-account>` or `GitHub <https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account>` for detailed steps. To enable SSH remote server access, add your public key to the file ``~/.ssh/authorized_keys`` of your user account on the SSH server.