GitHub SSH Keys: Formats Explained, Setup, and Common Issues

SSH Keys: Why They Exist and How They Work

Authenticating to remote servers, such as GitHub, traditionally involves sending a username and password. This method carries security risks, as passwords can be intercepted or require frequent input. SSH (Secure Shell) keys provide a more secure and convenient alternative by using cryptographic methods to verify identity without transmitting sensitive credentials like passwords over the network.

SSH keys operate on the principle of asymmetric cryptography, meaning they consist of a mathematically linked pair: a public key and a private key. Your private key resides on your local machine and must remain confidential. It acts as your unique digital signature. The corresponding public key is shared with any service you wish to access, like GitHub. Think of the private key as the key to your house, and the public key as a specific lock that only your key can open, installed on GitHub’s “door.”

When your local machine attempts to connect to GitHub, GitHub uses your stored public key to encrypt a challenge. Your machine then uses its private key to decrypt this challenge and send back the correct response. If the response is valid, GitHub confirms your identity, granting access. This exchange proves you possess the private key without ever exposing it to the network.

This authentication method is secure because your private key never leaves your local system. Even if an attacker intercepts the communication, they cannot reconstruct your private key from the public key or the challenge-response exchange. To set up SSH authentication, you generate a key pair on your local machine and then upload the public key to your GitHub account.

For example, generating an Ed25519 key pair, which is a modern and recommended algorithm, involves a command like this:

ssh-keygen -t ed25519 -C "[email protected]"

This command creates two files, typically id_ed25519 (your private key) and id_ed25519.pub (your public key), in your ~/.ssh/ directory. You then copy the contents of id_ed25519.pub to GitHub.

GitHub SSH Setup: Generating and Adding Keys

Secure access to GitHub repositories with SSH keys requires a local key pair. This pair consists of a private key, stored securely on your machine, and a public key, which you upload to GitHub.

Generate a new SSH key pair using the ssh-keygen command. The ED25519 algorithm is recommended for its security and performance. The -C flag adds a comment to the public key, typically your email, which helps identify the key later.

ssh-keygen -t ed25519 -C "[email protected]"

The command will prompt you for a file to save the key. The default location, ~/.ssh/id_ed25519, is usually appropriate. Press Enter to accept it. Next, you will be prompted to enter a passphrase. A passphrase encrypts your private key file, adding an important layer of security. If your private key is ever compromised, the passphrase prevents unauthorized use. Leaving it empty offers convenience but removes this security measure.

After generation, two files exist in your ~/.ssh/ directory: id_ed25519 (your private key) and id_ed25519.pub (your public key).

To avoid re-entering your passphrase with every SSH operation, use the ssh-agent. This program runs in the background, holding your decrypted private keys in memory. First, ensure the agent is running:

eval "$(ssh-agent -s)"

Agent pid 12345

Then, add your private key to the agent. If you set a passphrase, you will be prompted to enter it once.

ssh-add ~/.ssh/id_ed25519

Identity added: /home/user/.ssh/id_ed25519 ([email protected])

The next step is to add your public key to your GitHub account. Display the content of your public key file:

cat ~/.ssh/id_ed25519.pub

Copy the entire output, starting with ssh-ed25519 and ending with your email address. Navigate to GitHub, go to your profile settings, then “SSH and GPG keys”. Click “New SSH key”, provide a descriptive title for the key, and paste the copied public key content into the “Key” field. Click “Add SSH key”.

Finally, verify your SSH connection to GitHub:

ssh -T [email protected]

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

This message confirms that GitHub recognized your SSH key. You can now use Git commands with SSH.

SSH Key Formats: RSA, ED25519, and Their Differences

SSH keys use different cryptographic algorithms to secure connections. The two most common types encountered with services like GitHub are RSA and ED25519. Choosing between them involves a tradeoff between compatibility and modern cryptographic properties.

RSA is an older, widely supported public-key algorithm. It relies on the computational difficulty of factoring large prime numbers. RSA keys typically use sizes like 2048-bit or 4096-bit; larger keys offer more security but also increase computational overhead during key exchange and signing.

To generate an RSA key with a specific bit length, use the ssh-keygen command:

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa_github

The primary advantage of RSA is its near-universal compatibility across various SSH clients and servers, including older systems. Its main disadvantages are larger key sizes for equivalent security compared to modern alternatives, and slower performance during cryptographic operations.

ED25519 is a newer public-key algorithm based on elliptic-curve cryptography (ECC). It uses a fixed-size 256-bit key, which offers a security level comparable to a 3072-bit RSA key, but with significantly smaller key files and faster cryptographic operations.

Generating an ED25519 key is simpler, as it does not require specifying a bit length:

ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_github

ED25519 keys provide a stronger security posture and better performance compared to RSA. The algorithm is less susceptible to certain types of cryptographic attacks that can affect RSA. However, ED25519 might not be supported by very old SSH clients or servers, though this is rarely an issue with modern platforms like GitHub.

For new SSH key generations, ED25519 is the recommended choice. Its performance and security benefits make it superior for most current use cases. Use RSA primarily when specific legacy systems require it for compatibility. GitHub fully supports both formats.

How to Diagnose and Fix GitHub SSH Connection Problems

When an SSH connection to GitHub fails, the most common symptom is a “Permission denied (publickey)” message. This indicates the GitHub server did not accept any of the authentication keys presented by your client. The first step in diagnosing any SSH issue is to attempt a connection with verbose output, which reveals the keys your client offers and what the server accepts.

Run this command to test your connection and see detailed debug information:

ssh -vT [email protected]

Examine the output for lines containing “debug1: Offering public key:” or “Authentications that can continue:”. These lines show which keys your SSH client is attempting to use and which authentication methods the server supports.

A frequent cause of “Permission denied” is that your SSH agent is not running or does not know about your private key. The ssh-agent holds your decrypted private keys in memory, eliminating the need to enter your passphrase for each connection. Check if the agent is running and has keys loaded:

ssh-add -l

If no keys are listed, add your private key to the agent. Replace ~/.ssh/id_rsa with the correct path to your private key file if it has a different name:

ssh-add ~/.ssh/id_rsa

SSH requires strict file permissions for private keys and the .ssh directory. If these files or directories have overly permissive access, the SSH client will refuse to use them. Your private key file (e.g., id_rsa, id_ed25519) must be readable and writable only by the owner (600). The ~/.ssh directory should be accessible only by the owner (700). Correct these permissions:

chmod 600 ~/.ssh/id_rsa
chmod 700 ~/.ssh

GitHub must have the public half of your key registered to authenticate you. Copy your public key to the clipboard and verify its presence in your GitHub account settings under “SSH and GPG keys”. Ensure no leading or trailing whitespace characters are introduced when adding the key.

cat ~/.ssh/id_rsa.pub

If you manage multiple SSH keys, your client might attempt to use the wrong one for GitHub, or none at all. You can explicitly instruct SSH which key to use for specific hosts by configuring ~/.ssh/config. Create or edit this file to include an IdentityFile directive for GitHub:

Host github.com
  Hostname github.com
  User git
  IdentityFile ~/.ssh/id_ed25519 # Adjust to your key path, e.g., ~/.ssh/id_rsa
  IdentitiesOnly yes

The IdentitiesOnly yes directive ensures SSH only offers the keys specified by IdentityFile for this host, preventing it from trying other keys in your agent. After making changes, test the connection again with ssh -T [email protected].

Troubleshooting SSH: A Practical Exercise

A common scenario involves setting up a new SSH key for GitHub, adding its public component to your GitHub account, yet still encountering Permission denied when attempting to interact with a repository. Consider a colleague who has generated a new ED25519 key at ~/.ssh/github_id_ed25519 and added github_id_ed25519.pub to GitHub. When they try to clone a private repository, they receive:

[email protected]:Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

The first step in diagnosing any SSH connection issue is to increase verbosity. Use the -vT flags with the ssh command to make it test the connection and print detailed debug information.

ssh -vT [email protected]

Examine the output carefully. Look for lines indicating which keys ssh is attempting to offer. A typical problem might show debug1: Offering public key: /Users/user/.ssh/id_rsa RSA SHA256:... followed by debug1: No more authentication methods to try. This output suggests ssh is only trying the default id_rsa key, or no key at all, rather than the intended github_id_ed25519.

This indicates that the SSH client is not aware of the correct key. Two primary solutions address this.

First, ensure your ssh-agent is running and has the correct key loaded. The ssh-agent manages your private keys, preventing repeated password prompts. If ssh-agent is not running, start it using eval "$(ssh-agent -s)". Then, add your specific key to the agent:

eval "$(ssh-agent -s)" # Only if agent is not running
ssh-add ~/.ssh/github_id_ed25519

After adding the key, re-test the connection with ssh -vT [email protected]. The verbose output should now show debug1: Offering public key: /Users/user/.ssh/github_id_ed25519 ED25519 SHA256:.... If the connection succeeds, you can proceed with Git operations.

For a more permanent solution, or if you manage multiple keys for different hosts, define your key usage in ~/.ssh/config. Create or edit this file and add an entry for GitHub:

Host github.com
  Hostname github.com
  User git
  IdentityFile ~/.ssh/github_id_ed25519
  IdentitiesOnly yes

The IdentitiesOnly yes directive ensures ssh only tries the specified IdentityFile for github.com, preventing it from offering other keys unnecessarily. Save the config file and re-test. This approach explicitly tells ssh which key to use for GitHub, bypassing the need to manually add it to ssh-agent each session, though ssh-agent is still needed for passphrase management.