Enhance SSH documentation for Nitrokey usage

Updated SSH section to include GitLab and GitHub references, clarified passphrase usage, and improved overall text flow.

Author: jans23

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

@@ -3,9 +3,7 @@ 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. 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.
+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
 ------------------
@@ -26,10 +24,6 @@ Generating SSH Key
 
       ssh-keygen -t ed25519-sk -O resident -C "your_comment"
 
-   .. warning::
-
-      The ``-O resident`` option stores key handles on the Nitrokey, allowing others with physical access to list them and see where the key was used.
-
    .. note::
 
       Resident keys can later be listed and imported on another system with:
@@ -39,13 +33,13 @@ Generating SSH Key
          ssh-keygen -K
 
 
-4. 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 key files. Using both increases overall security.
+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.
 
-5. When asked for a file path, accept the default option (``~/.ssh/id_ed25519_sk``) or choose a custom name like ``id_ed25519_sk_gitlab``.
+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``.
 
-6. If the Nitrokey blinks, confirm the operation by touching it.
+5. If the Nitrokey blinks, confirm the operation by touching it.
 
-7. By executing the command, the following files will be created:
+Eventually the following files will be created:
 
    ``~/.ssh/id_ed25519_sk`` → handle to the private key (stored securely on the Nitrokey)
 
@@ -64,8 +58,6 @@ 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.
 
-For Git Services (GitLab, GitHub, etc.) 
-
 1. Display your public key:
 
    .. code-block:: shell-session
@@ -76,9 +68,4 @@ For Git Services (GitLab, GitHub, etc.)
       
       [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 (from ``~/.ssh/id_ed25519_sk.pub``) to the ``~/.ssh/authorized_keys`` file of the user account. This allows passwordless authentication using your Nitrokey.
+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.