SSH (Secure Shell) keys are cryptographic credentials that enable secure authentication between systems. They consist of two components: a public key that can be shared freely, and a private key that must be kept secure. When using Git with remote repositories, SSH keys provide a robust alternative to password-based authentication.

The authentication process works through public-key cryptography: your private key remains on your local machine, while the public key is stored on the remote Git server. When establishing a connection, the server uses the public key to create an encrypted message that only your private key can decrypt, thus verifying your identity without transmitting sensitive information.

This approach offers several advantages over traditional passwords:

  • Enhanced security through cryptographic verification.
  • No need to manually enter credentials.
  • Protection against brute force attacks.
  • Ability to revoke access by removing public keys.

Generate a new SSH key for GitHub

Before generating SSH keys for GitHub, it is essential to verify that the email address matches the one associated with the GitHub account. This practice ensures proper key management and maintains consistency.

The Ed25519 algorithm represents the recommended choice for new SSH keys, offering enhanced security characteristics and superior performance:

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

Using RSA (alternative)

For systems lacking Ed25519 support, RSA with 4096 bits provides a robust alternative:

ssh-keygen -t rsa -b 4096 -C "[email protected]"

Key generation process

The key generation procedure involves the following steps:

  1. Accept the default file location (~/.ssh/id_ed25519 or ~/.ssh/id_rsa). The standard path enables automatic key detection by SSH and Git systems. Custom locations require additional configuration in ~/.ssh/config.
  2. Enter a secure passphrase (strongly recommended).
  3. Confirm the passphrase entry.

The process generates two distinct files:

  • Private key: ~/.ssh/id_ed25519 (or id_rsa)
  • Public key: ~/.ssh/id_ed25519.pub (or id_rsa.pub)

🔒 Security Note: Never share the private key and always protect it with a strong passphrase.

Generated SSH keys

Configure the SSH agent

The SSH agent functionality requires proper installation and configuration. To verify the installation status and operational state:

eval "$(ssh-agent -s)"

A successful execution will display: Agent pid XXXX, where XXXX represents the process identifier.

Systemd configuration

On systemd-based distributions, the SSH agent can be configured as a persistent service:

systemctl enable --now --user ssh-agent.service

Alternative configuration

For non-systemd environments, the SSH agent can be initialized through shell configuration files. Add the following command to .zprofile or the appropriate shell startup script:

eval "$(ssh-agent -s)"

Key registration

After configuring the SSH agent, register the private key:

ssh-add ~/.ssh/id_ed25519

To verify the registered keys:

ssh-add -l

Add the public SSH key to GitHub

The registration of the public key in the GitHub account is required. This option is accessible through the following path: Settings > SSH and GPG keys in the GitHub profile interface.

Add new SSH key to GitHub

Select the New SSH key button and proceed to enter an identifiable label for the key along with the corresponding public key content.

SSH key added

Upon successful key registration, repository access can be configured either by modifying existing remotes or by performing a new clone operation using the SSH URL format.

Git clone using SSH

git clone [email protected]:tanisperez/dotfiles.git

The implementation of this SSH URL format enables automatic authentication through the configured SSH key during repository operations.

Configure SSH keys for different hosts

When working with multiple Git hosting services or requiring distinct authentication credentials for different hosts, SSH configuration allows the specification of unique key files for each remote server. This configuration is managed through the SSH client configuration file.

The following example demonstrates the basic structure for host-specific SSH key configuration in the ~/.ssh/config file:

# GitHub configuration
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/github_ed25519
    AddKeysToAgent yes

# GitLab configuration
Host gitlab.com
    HostName gitlab.com
    User git
    IdentityFile ~/.ssh/gitlab_ed25519
    AddKeysToAgent yes

# Company GitLab instance
Host gitlab.company.com
    HostName gitlab.company.com
    User git
    IdentityFile ~/.ssh/company_ed25519
    AddKeysToAgent yes
    PreferredAuthentications publickey

This configuration enables the automatic selection of the appropriate SSH key when connecting to specific hosts.

Troubleshooting common issues

Permission denied

If encountering Permission denied (publickey) errors:

ssh -vT [email protected]

This verbose output helps identify authentication issues.

Wrong key used

To force SSH to use a specific key:

ssh -i ~/.ssh/specific_key -T [email protected]

Agent issues

If the SSH agent is not responding:

eval "$(ssh-agent -s)"
ssh-add -l

References