.. _ssh_authentication: ============================ Authentication with SSH Keys ============================ .. contents:: In this section: :local: :depth: 2 SSH key authentication is a more secure and convenient method of accessing the GridUnesp cluster. Once configured, you can connect without having to type your password every time. .. note:: Currently, GridUnesp **requires password authentication**. This guide is provided for future reference in case SSH keys are enabled, and for use with other services. How SSH Keys Work ================= SSH keys work in pairs: - **Private Key**: Stays on your computer, must **NEVER** be shared - **Public Key**: Stays on the server (GridUnesp), can be shared When you try to connect, the server checks whether you possess the private key corresponding to the registered public key. Generating an SSH Key Pair ========================== Linux and macOS --------------- Open a terminal and run: .. code-block:: bash # For Ed25519 keys (recommended) ssh-keygen -t ed25519 -C "your-email@example.com" # Or for broader compatibility (RSA) ssh-keygen -t rsa -b 4096 -C "your-email@example.com" You will see: .. code-block:: text Generating public/private ed25519 key pair. Enter file in which to save the key (/home/usuario/.ssh/id_ed25519): [Enter] Enter passphrase (empty for no passphrase): [type a strong passphrase] Enter same passphrase again: [repeat] **Recommendation:** Always use a passphrase to protect your private key. Files generated: - **Private key:** ``~/.ssh/id_ed25519`` (NEVER share this!) - **Public key:** ``~/.ssh/id_ed25519.pub`` (will be copied to the server) Windows (PowerShell) -------------------- Open PowerShell and run: .. code-block:: powershell ssh-keygen -t ed25519 -C "your-email@example.com" Follow the same instructions as for Linux/macOS. Windows (PuTTYgen) ------------------ 1. Download and open PuTTYgen (included in the PuTTY installer) 2. Select "Ed25519" or "RSA" (with 4096 bits) 3. Click "Generate" and move the mouse randomly 4. Type a strong passphrase under "Key passphrase" 5. Save the private key: "Save private key" (.ppk file) 6. Copy the public key text (will be used in the next step) Copying the Public Key to GridUnesp =================================== .. attention:: **This procedure is NOT currently available** because GridUnesp uses password-only authentication. If/when SSH keys are enabled, you will be able to use one of the methods below. Method 1: ssh-copy-id (Linux/macOS) ----------------------------------- .. code-block:: bash ssh-copy-id your-username@access.grid.unesp.br Type your password when prompted. The public key will be added automatically. Method 2: Manual Copy --------------------- 1. View your public key: .. code-block:: bash cat ~/.ssh/id_ed25519.pub 2. Connect to GridUnesp normally: .. code-block:: bash ssh your-username@access.grid.unesp.br 3. On the server, add the key to the authorized_keys file: .. code-block:: bash mkdir -p ~/.ssh chmod 700 ~/.ssh echo "YOUR_PUBLIC_KEY_HERE" >> ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys 4. Exit and reconnect — it should now work without a password (or only requiring the key passphrase) Configuring the ~/.ssh/config File ================================== To make connecting easier, create or edit the ``~/.ssh/config`` file: .. code-block:: text Host gridunesp HostName access.grid.unesp.br User your-username IdentityFile ~/.ssh/id_ed25519 ServerAliveInterval 60 ServerAliveCountMax 5 You can now connect simply with: .. code-block:: bash ssh gridunesp **Advantages:** - Faster: just ``ssh gridunesp`` - More convenient: no need to remember the full hostname - Automatic keep-alive: keeps the connection active Using ssh-agent =============== To avoid having to type the key passphrase at every connection, use ssh-agent: Linux/macOS ----------- .. code-block:: bash # Start ssh-agent eval $(ssh-agent) # Add your key ssh-add ~/.ssh/id_ed25519 # Type the key passphrase once On macOS, you can add it permanently to the keychain: .. code-block:: bash ssh-add --apple-use-keychain ~/.ssh/id_ed25519 Windows (PowerShell) -------------------- .. code-block:: powershell # Start service (if not already active) Get-Service ssh-agent | Set-Service -StartupType Automatic -PassThru | Start-Service # Add key ssh-add $env:USERPROFILE\.ssh\id_ed25519 Troubleshooting =============== Incorrect Permissions --------------------- If the permissions are not correct, SSH may refuse to use the keys: .. code-block:: bash # Fix permissions on the client chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519 chmod 644 ~/.ssh/id_ed25519.pub chmod 600 ~/.ssh/config # Fix permissions on the server ssh your-username@access.grid.unesp.br chmod 700 ~/.ssh chmod 600 ~/.ssh/authorized_keys Connection Still Asks for Password ---------------------------------- 1. Check whether the key was copied correctly: .. code-block:: bash ssh your-username@access.grid.unesp.br cat .ssh/authorized_keys 2. Use verbose mode for debugging: .. code-block:: bash ssh -v your-username@access.grid.unesp.br 3. Check whether the correct key is being used: .. code-block:: bash ssh -v -i ~/.ssh/id_ed25519 your-username@access.grid.unesp.br Error: "Permissions 0644 for 'id_rsa' are too open" --------------------------------------------------- .. code-block:: bash chmod 600 ~/.ssh/id_ed25519 Error: "Agent admitted failure to sign" --------------------------------------- Restart ssh-agent and add the key again: .. code-block:: bash eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519 Security Best Practices ======================= 1. **ALWAYS** protect your private key with a strong passphrase 2. **NEVER** share your private key with anyone 3. **Use different keys** for different services (GridUnesp, GitHub, etc.) 4. **Back up** your private key in a secure (encrypted) location 5. **Rotate your keys** periodically (every 1–2 years) 6. **Remove old keys** from the server when they are no longer used 7. **Use Ed25519** whenever possible (more secure and faster than RSA) Verifying Fingerprints ====================== When connecting for the first time, SSH will show the server fingerprint: .. code-block:: text The authenticity of host 'access.grid.unesp.br (200.145.46.48)' can't be established. ED25519 key fingerprint is SHA256:+HEvFMmo0EA6ipPMJSaj5+Q6IabebRN+nRD0nxdYrKQ. Are you sure you want to continue connecting (yes/no)? **Check whether it matches one of the official GridUnesp fingerprints:** .. code-block:: text RSA: SHA256:X3iCb13fWj7u2Tvp/MCCpn0brfSNS5Ie6ehm6lsvPSQ ECDSA: SHA256:WVFokXOLnuH9+2e7xxRU2gp7XJqxwuE6H8bbUMqTCXo ED25519: SHA256:+HEvFMmo0EA6ipPMJSaj5+Q6IabebRN+nRD0nxdYrKQ If it matches, type ``yes`` and press Enter. .. seealso:: - :ref:`accessing_the_cluster` - Basic cluster access - :ref:`security` - Security procedures - `SSH Academy `_ - Complete SSH documentation