Overcoming SSH Publickey issues in Linux Terminal

If you’re a frequent user of SSH, you might have encountered the “Permission Denied (publickey)” error, which can cause a lot of frustration and confusion. As someone who has spent a considerable amount of time working with terminal screens, I can relate to the challenges of SSH.

In this post, I will share my personal experiences and provide you with practical solutions to solve this common issue. Through personal anecdotes and practical examples, you will learn how to tackle this problem with ease.

Understanding the error: It’s not you, it’s SSH

First off, let’s get something straight – encountering an SSH public key error doesn’t mean you’re doing something wrong. SSH, or Secure Shell, is a network protocol that provides a secure channel over an unsecured network. It uses a pair of keys (public and private) to authenticate. When you see “Permission Denied (publickey),” it’s SSH’s way of saying, “Hey, I don’t recognize this key.”

Why does this error happen?

Common reasons include:

• Wrong SSH key: You might be using a key that the server doesn’t recognize.
• Incorrect file permissions: SSH is picky about file permissions for security reasons.
• SSH configuration issues: Sometimes, the server or client configuration might be off.

When you encounter a “Permission Denied (publickey)” error in SSH, the terminal output typically looks something like this:

$ ssh fosslinux@server.com
Permission denied (publickey).

Here’s a more detailed example that includes some common debugging information:

$ ssh -vvv fosslinux@server.com
OpenSSH_7.6p1 Ubuntu-4ubuntu0.3, OpenSSL 1.0.2n  7 Dec 2017
debug1: Reading configuration data /home/fosslinux/.ssh/config
debug1: /home/fosslinux/.ssh/config line 20: Applying options for server.com
debug1: Reading configuration data /etc/ssh/ssh_config
debug2: resolving "server.com" port 22
debug2: ssh_connect_direct: needpriv 0
debug1: Connecting to server.com [192.168.1.1] port 22.
debug1: Connection established.
...
debug1: Offering public key: RSA SHA256:yourkeyfingerprint /home/fosslinux/.ssh/id_rsa
debug3: send_pubkey_test
debug3: waiting for SSH2_MSG_USERAUTH_FAILURE
debug1: Authentications that can continue: publickey
debug1: Trying private key: /home/fosslinux/.ssh/id_dsa
debug3: no such identity: /home/fosslinux/.ssh/id_dsa: No such file or directory
debug1: Trying private key: /home/fosslinux/.ssh/id_ecdsa
debug3: no such identity: /home/fosslinux/.ssh/id_ecdsa: No such file or directory
debug1: Trying private key: /home/fosslinux/.ssh/id_ed25519
debug3: no such identity: /home/fosslinux/.ssh/id_ed25519: No such file or directory
debug2: we did not send a packet, disable method
debug1: No more authentication methods to try.
fosslinux@server.com: Permission denied (publickey).

Diagnosing the problem: Like a detective with a terminal

Understanding SSH keys and the SSH agent

SSH (Secure Shell) uses public key cryptography for secure communications. When you set up SSH keys, you generate a pair:

• Private key: This is kept secret and secure on your client machine.
• Public key: This is placed on the server in a file (typically ~/.ssh/authorized_keys).

The SSH agent is a background program that handles keys for SSH. It keeps your private keys in memory, ready for use by SSH client programs. This means you don’t have to enter your passphrase every time you use an SSH or SCP command.

Step 1: Listing loaded keys with ssh-add -l

Running ssh-add -l: This command lists all the private keys that the SSH agent currently holds.

ssh-add -l

Example Output:

2048 SHA256:xyz123abc /your/home/.ssh/id_rsa (RSA)

The output shows the key’s bit length, its fingerprint (a unique identifier), and the file path of the private key.

• • Here, 2048 is the bit length, SHA256:xyz123abc is the fingerprint, /your/home/.ssh/id_rsa is the file path, and (RSA) indicates the type of key.

Step 2: Adding your key to the SSH agent

If your desired key isn’t listed in the output of ssh-add -l, you need to add it to the SSH agent.

Using ssh-add to add a key:

ssh-add /path/to/your/private/key adds your private key to the SSH agent.

Replace /path/to/your/private/key with the actual path to your private key file.

ssh-add ~/.ssh/id_rsa

Entering your passphrase:

If your key is protected by a passphrase (which it should be for security), you’ll be prompted to enter it. Once entered, the key will be added to the SSH agent.

Verifying: Run ssh-add -l again to ensure your key is now listed.

ssh-add -l

Checking SSH keys

First, ensure you’re using the correct SSH key. Run ssh-add -l to list the keys your SSH agent has loaded.

Sample output:

2048 SHA256:xyz123abc /fosslinux/home/.ssh/id_rsa (RSA)

If your key isn’t listed, add it using:

 ssh-add /path/to/your/private/key

Verifying file permissions

SSH requires specific permissions for files in your ~/.ssh directory. Your private key should be read-only for you, and nothing else. Use ls -l ~/.ssh to check permissions.

Sample output:

-rw------- 1 user user 1679 Jan  1 12:34 id_rsa

If permissions are off, correct them using chmod. For example, chmod 600 ~/.ssh/id_rsa.

Checking SSH configurations

Sometimes, it’s not about the keys but the configuration. Check /etc/ssh/sshd_config on the server and ~/.ssh/config on your client. Look for directives like PubkeyAuthentication and AuthorizedKeysFile. Let me explain a bit more about how to do it.

Server-Side configuration: /etc/ssh/sshd_config

On the server side, the configuration is managed through the sshd_config file. This file controls the SSH daemon settings, including how it handles authentication.

Accessing sshd_config:

To view or edit this file, you typically need superuser access. Use the following command:

sudo nano /etc/ssh/sshd_config

(or replace nano with your preferred text editor).

Output: Look for lines resembling the following in the sshd_config file:

PubkeyAuthentication yes
AuthorizedKeysFile .ssh/authorized_keys

What to look for:

• • PubkeyAuthentication: This line should read PubkeyAuthentication yes to enable authentication using public keys.
  • AuthorizedKeysFile: This specifies the file where the authorized keys are stored, usually .ssh/authorized_keys or similar.

Making changes:

If you make any changes, save the file and restart the SSH service using a command like:

sudo systemctl restart sshd

Client-Side Configuration: ~/.ssh/config

On the client side, SSH settings are controlled through a file in your user’s home directory, typically ~/.ssh/config.

Accessing config:

Open this file with a text editor:

 nano ~/.ssh/config

If it doesn’t exist, you can create it.

What to include:

Here, you can specify settings for individual hosts or global settings. For instance, you can specify which private key to use for a particular server.

Example: To use a specific key for a specific host, you might add:

Host example.com
IdentityFile ~/.ssh/example_id_rsa

After editing, save the file. These changes do not require restarting any service and will be used the next time you initiate an SSH connection.

Fixing the issue: A step-by-step guide

Step 1: Ensuring you’re using the right key

1. List your loaded keys:
   • Run ssh-add -l to see a list of the keys your SSH agent currently has loaded.
   • This helps you confirm if the key you intend to use for your SSH connection is actually available to the SSH client.
2. Add your key to the SSH agent:
   • If your key isn’t listed, add it using ssh-add /path/to/your/private/key.
   • Replace /path/to/your/private/key with the actual file path of your private key.
   • If prompted, enter your passphrase for the private key.

Step 2: Setting the correct permissions

SSH is very particular about file permissions for security reasons. Incorrect permissions can be a reason for SSH to deny access.

1. Permissions for Your Private Key:
   • Your private key file should only be readable by you. The recommended permission setting is 600.
   • Run chmod 600 ~/.ssh/id_rsa (replace id_rsa with your key filename if different).
2. Permissions for the ~/.ssh Directory:
   • The ~/.ssh directory should also have restricted permissions, typically 700.
   • Run chmod 700 ~/.ssh.

Step 3: Verifying SSH configurations on the server

This involves checking the SSH daemon configuration file (sshd_config) on the server to ensure it’s set up to accept public key authentication.

1. Access the SSH configuration file:
   • You need to access /etc/ssh/sshd_config on the server. This usually requires root or sudo privileges.
   • Use a command like sudo nano /etc/ssh/sshd_config.
2. Check for PubkeyAuthentication:
   • Look for a line that says PubkeyAuthentication yes. This line enables login using SSH keys.
   • If it’s not there, add it or uncomment it (remove the # at the beginning of the line).
3. Restart the SSH service:
   • After making changes, save the file and restart the SSH service to apply them.
   • Use sudo systemctl restart sshd or the appropriate command for your server’s operating system.

Additional tips:

• Testing Without Logout: When you change sshd_config, it’s a good practice to restart the SSH service and try a new SSH connection without logging out of your current session, just in case something goes wrong.
• Check for Typos: A simple typo in the sshd_config file or in the key filename/path can cause issues.
• Client Configuration: Rarely, the issue might also be in your local SSH client configuration (~/.ssh/config). Ensure there are no conflicting settings there.

Conclusion: Triumph over terminal

Dealing with SSH key errors can be complicated, but it’s possible to overcome this hurdle with the right approach. One common error message is “Permission Denied (publickey)”, which may seem overwhelming at first. However, it’s often caused by simple configuration mistakes or overlooked settings. By methodically checking that you have the correct SSH key, setting the appropriate file permissions, and verifying server-side configurations, you can ensure a smooth SSH experience.