Docs: update SSH Authentication (ssh.rst)

Author: ABuljko

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

@@ -3,15 +3,9 @@ SSH Authentication with FIDO2
 
 .. product-table:: nk3 passkey fido2
 
-Use your Nitrokey for secure SSH login to servers, GitLab, or GitHub.  
-The private key is generated and safely stored inside the device, ensuring it never leaves the hardware.  
-Authentication requires a physical touch of the Nitrokey, providing strong protection against phishing and unauthorized access.
+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.
 
-What is SSH?
-------------
-
-**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 while maintaining 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.
 
 Generating SSH Key
 ------------------
@@ -24,8 +18,8 @@ Generating SSH Key
 
       ssh-keygen -t ed25519-sk -C "your_comment"
 
-3. Optionally you can also turn your key into a resident key, allowing it to be used on other computers without copying files. By default, SSH FIDO2 keys created with ``-t ed25519-sk`` are non-resident keys, meaning a local key handle is stored in ``~/.ssh/`` while the private key remains securely on the Nitrokey. Using ``-O resident`` is optional and provides portability across systems. For single-system use, the standard ``ssh-keygen -t ed25519-sk`` command is sufficient.Optionally you can also turn your key into a resident key, allowing it to be used on other computers without copying files. By default, SSH FIDO2 keys created with ``-t ed25519-sk`` are non-resident keys, meaning a local key handle is stored in ``~/.ssh/`` while the private key remains securely on the Nitrokey. Using ``-O resident`` is optional and provides portability across systems. For single-system use, the standard ssh-keygen ``-t ed25519-sk`` command is sufficient.
-         
+3. You can optionally create a resident key, allowing it to be used on other computers without copying files. By default, SSH FIDO2 keys created with -t ed25519-sk are non-resident, meaning a local key handle is stored in ~/.ssh/ while the private key remains securely on the Nitrokey. Using -O resident provides portability across systems, but for single-system use, the standard ssh-keygen -t ed25519-sk command is sufficient.
+
    .. code-block:: shell-session
 
       ssh-keygen -t ed25519-sk -O resident -C "your_comment"
@@ -44,9 +38,7 @@ Generating SSH Key
 
 6. If the Nitrokey blinks, confirm the operation by touching it.
 
-7. Optionally you can also set a passphrase (it is usually recommended for security reasons but not mandatory).
-
-8. By executing the command, the following files will be created:
+7. By executing the command, the following files will be created:
 
    ``~/.ssh/id_ed25519_sk`` → handle to the private key (stored securely on the Nitrokey)
 
@@ -60,18 +52,40 @@ Generating SSH Key
    :alt: img0
 
 
-Adding your Public Key to GitLab or GitHub
-------------------------------------------
-1. Enter this command to view your public key in the terminal
+Adding Your Public Key
+----------------------
 
-   .. code-block:: shell-session 
+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
 
-      cat ~/.ssh/id_ed25519_sk.pub 
+      cat ~/.ssh/id_ed25519_sk.pub
 
    Example output (do not use this key)::
    
-      [email protected] AAAAGnNrLXNzaC1lZDI1NTE5QG7wZW4zc2guY29tAAAAILeZl6r07HV4i1rK07OfLqD3J4IzX2q0lB6Ok0pdxoG5AAAABHNzaDo= your_comment #. Copy the key to your account...
+      [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.
+
+
+**For Remote Servers**  
+To allow SSH access, the same public key must be listed in the server’s ``~/.ssh/authorized_keys`` file.  
+During authentication, the server checks for a matching key and verifies your identity through a challenge signed by your Nitrokey’s private key.
+
+To add your key:
+
+.. code-block:: shell-session
 
-2. Add the copied SSH key to your accounts designated SSH Key Field.
+   mkdir -p ~/.ssh
+   chmod 700 ~/.ssh
+   cat ~/.ssh/id_ed25519_sk.pub >> ~/.ssh/authorized_keys
+   chmod 600 ~/.ssh/authorized_keys
 
-   See instructions for `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>`.
+Each line in ``authorized_keys`` represents one trusted key. 
+ 
+You can add multiple keys or restrict usage, for example to a specific IP range and command:
+   from="192.168.0.*" command="/usr/local/bin/backup.sh" [email protected] AAAAGnNrLXNzaC1lZDI1NTE5QG7wZW4zc2guY29tAAAAILeZl6r07HV4i1rK07OfLqD3J4IzX2q0lB6Ok0pdxoG5AAAABHNzaDo= your_comment