HowTo :: SSH access using a GPG key for authentication

Date: 2018-10-02

Last Modified: 2026-02-01

Reading Time: 8 mins

Section: HowTo

Categories: howto

Introduction

Replace traditional SSH keys with GPG authentication subkeys, reducing the number of keys to manage while enabling GPG web of trust for SSH access distribution.

What is This About?

Many of us are familiar with Secure Shell (SSH), which allows us to connect to other systems using a key instead of a password. This guide will explain how to eliminate SSH keys and use a GNU Privacy Guard (GPG) subkey instead.

Important clarification: Using GPG does not make your SSH connections more secure. SSH is already a secure protocol, and SSH keys are secure. Instead, this approach provides:

Simplified key management - One GPG key replaces multiple SSH keys
Better backup strategy - Fewer keys to secure and back up
GPG web of trust integration - Leverage existing GPG key distribution infrastructure
Easier key distribution - Share keys via public keyservers instead of manual transfer

Your SSH workflow remains unchanged - all commands work as expected, except you’ll unlock your GPG key instead of managing separate SSH private keys.

Why Use GPG for SSH?

Traditional SSH key distribution requires manual transfer (“send me your public key”). With GPG, you can distribute SSH keys via public keyservers using the established GPG web of trust. Organizations like The Monkeysphere Project are building on this capability.

What You’ll Need

Prerequisites

Before starting, ensure you have:

Existing GPG key pair - If you don’t have one, see Fedora’s GPG key creation guide
SSH access to a remote system - For testing your setup
gpg2 and gpg-agent installed (standard on most Linux distributions)
Good passphrase hygiene - Your GPG key will authenticate SSH connections

Key Security Reminder

By having SSH authenticated by your GPG key, you reduce the number of key files to manage. However, your key management hygiene must still be excellent:

Choose strong passphrases
Never back up private keys to the cloud
Use appropriate key preservation strategies
Consider hardware tokens for additional security

Understanding GPG Subkeys

A GPG key is actually a collection of keys, not just one:

Primary key - Used for signing and certification
Encryption subkey - Created by default, used for encryption
Authentication subkey - What we’ll create for SSH

Subkeys are separate keys signed by your primary key and transmitted together. This architecture allows you to revoke individual subkeys (e.g., if compromised) while keeping your primary key valid.

For SSH, we’ll create an authentication subkey that completely replaces traditional SSH keypairs generated with ssh-keygen. You can create multiple authentication subkeys if you need different SSH keys for different purposes.

Subkey Benefits

Revocation flexibility - Revoke compromised subkeys without affecting your primary key
Selective distribution - Share only the subkeys you need for specific purposes
Backup simplicity - Treat all keys as one for backup, but use them independently

Step-by-Step Guide

Step 1: Create an Authentication Subkey

You’ll create the subkey by editing your existing GPG key in expert mode to access authentication options.

Start the key editing process:

1
gpg2 --expert --edit-key <KEY_ID>

Finding Your Key ID

List your GPG keys to find the key ID:

1
gpg2 --list-keys

Use the 40-character fingerprint or the 8-character short ID shown in the output.

In the GPG prompt, add a new key:

1
gpg> addkey

Select key type 8 (RSA with custom capabilities):

Your selection? 8

Toggle capabilities to enable only Authentication:

Type s to disable signing
Type e to disable encryption
Type a to enable authentication
Type q when only “Authenticate” is shown

Possible actions for a RSA key: Sign Encrypt Authenticate
Current allowed actions: Sign Encrypt

Your selection? s
Your selection? e
Your selection? a

Current allowed actions: Authenticate

Your selection? q

Choose key size. SSH typically uses 2048-bit, but 4096-bit provides additional security:

What keysize do you want? (2048) 4096

Set expiration. Consider setting an expiration date (e.g., 2 years) as a security best practice:

Key is valid for? (0) 2y

Or choose no expiration if you prefer:

Key is valid for? (0) 0

Confirm your choices and enter your passphrase when prompted. You should see output showing your new authentication subkey (marked with usage: A):

ssb rsa4096/136F0B4E3D42CF31
    created: 2019-03-21  expires: never     usage: A

Save and exit:

gpg> quit
Save changes? (y/N) y

Remember Your Passphrase

You’ll need your GPG passphrase every time you use SSH. Consider using a passphrase manager or gpg-agent caching to avoid repeated entry.

Step 2: Configure gpg-agent for SSH

The gpg-agent program will handle SSH authentication requests instead of ssh-agent.

Enable SSH support in gpg-agent by adding this line to ~/.gnupg/gpg-agent.conf:

1
echo "enable-ssh-support" >> ~/.gnupg/gpg-agent.conf

Verify the configuration:

1
cat ~/.gnupg/gpg-agent.conf

You should see:

enable-ssh-support

Optional: Additional gpg-agent Settings

Consider adding these options to ~/.gnupg/gpg-agent.conf:

default-cache-ttl 600
max-cache-ttl 7200

This caches your passphrase for 10 minutes (600 seconds), with a maximum of 2 hours.

Step 3: Pre-configure SSH Keys (Optional)

You can pre-specify which keys to use for SSH to avoid running ssh-add each time.

Find your authentication subkey’s keygrip:

1
gpg2 -K --with-keygrip

Look for the subkey with [A] (authentication) capability:

ssb   rsa2048 2019-03-21 [A]
      Keygrip = 2BE91C3C443AA29C3703D004587AD6DA9D7E40FC

Add the keygrip to sshcontrol:

1
echo "2BE91C3C443AA29C3703D004587AD6DA9D7E40FC" >> ~/.gnupg/sshcontrol

Replace the keygrip above with your actual keygrip value.

What is a Keygrip?

A keygrip is an internal identifier gpg-agent uses to refer to keys. Unlike a key hash, a keygrip refers to both the public and private key together.

Step 4: Configure Shell Environment

Tell SSH how to access gpg-agent by setting the SSH_AUTH_SOCK environment variable.

Add these lines to ~/.bashrc (or ~/.zshrc if using zsh):

1
2
export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
gpgconf --launch gpg-agent

Apply the configuration to your current session:

1
source ~/.bashrc

Or start a new terminal session.

For Zsh Users

If you use zsh instead of bash, add the same lines to ~/.zshrc instead of ~/.bashrc.

Step 5: Verify the Setup

Check that gpg-agent is providing your SSH key:

1
ssh-add -L

You should see your GPG-based SSH public key printed. The key will have a comment indicating it’s from GPG.

If you see “The agent has no identities,” restart gpg-agent:

1
2
3
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent
ssh-add -L

Distribute your public key to remote systems just like traditional SSH keys.

Option 1: Manual copy

1
ssh-add -L

Copy the output and manually add it to ~/.ssh/authorized_keys on the remote system.

Option 2: Use ssh-copy-id (recommended)

1
ssh-copy-id user@remote-host

This automatically copies your public key to the remote system.

Nothing Changes for Remote Hosts

The remote systems you connect to don’t need any configuration changes. They see your GPG authentication subkey as a standard SSH public key.

Step 7: Test SSH Connection

Connect to a remote system as usual:

1
ssh user@remote-host

You should be prompted for your GPG passphrase instead of an SSH key passphrase. After successful authentication, your passphrase will be cached according to your gpg-agent configuration.

Troubleshooting

Common Issues

Issue: ssh-add -L shows “The agent has no identities” Solution:

Verify ~/.gnupg/sshcontrol contains your authentication keygrip
Restart gpg-agent: gpgconf --kill gpg-agent && gpgconf --launch gpg-agent
Check SSH_AUTH_SOCK is set: echo $SSH_AUTH_SOCK

Issue: SSH still asks for password instead of GPG passphrase Solution:

Ensure your public key is in ~/.ssh/authorized_keys on the remote system
Run ssh-add -L to verify your key is available
Check SSH connection with verbose output: ssh -v user@host

Issue: “sign_and_send_pubkey: signing failed: agent refused operation” Solution:

Your GPG key might be locked or expired
Try unlocking it: echo "test" | gpg2 --sign --armor
Verify key expiration: gpg2 -K

Issue: gpg-agent not starting automatically Solution:

Verify ~/.bashrc contains the export and launch commands
Source your bashrc: source ~/.bashrc
Start a new terminal session

Issue: Passphrase asked every time despite caching Solution:

Check ~/.gnupg/gpg-agent.conf has cache settings
Restart gpg-agent after config changes
Consider using pinentry for better passphrase caching

Key Management Best Practices

Maintaining Your GPG-SSH Setup

Regular backups - Export and securely store your GPG key: gpg2 --export-secret-keys KEY_ID > private-key-backup.gpg
Revocation certificate - Create one when you first make your key: gpg2 --gen-revoke KEY_ID > revoke-cert.asc
Key expiration - Set reasonable expiration dates and renew before they expire
Subkey rotation - Periodically create new authentication subkeys and revoke old ones
Monitor usage - Check ~/.gnupg/sshcontrol to see which keys are in use
Test recovery - Periodically test your backup and recovery procedures

Next Steps

Now that you have GPG-based SSH authentication:

Distribute via keyserver - Upload your GPG key to public keyservers so others can fetch your SSH key
Explore Monkeysphere - Visit The Monkeysphere Project to learn about GPG web of trust for SSH
Hardware tokens - Consider using a YubiKey or other hardware token to store your GPG key
Multiple authentication subkeys - Create different subkeys for different systems or purposes
Remove old SSH keys - Once confident in your GPG setup, remove traditional SSH keys: rm ~/.ssh/id_rsa*

GPG Web of Trust for SSH

With GPG-authenticated SSH, you can leverage the GPG web of trust:

Others can fetch your SSH key from keyservers
Key signing parties can authenticate SSH keys
Centralized key management for organizations
Automatic key rotation when you update your GPG key

Congratulations!

You’ve successfully enabled SSH access using GPG authentication! Your SSH workflow remains identical from a user perspective, but you’ve gained:

Reduced number of keys to manage and back up
Ability to use GPG key distribution infrastructure for SSH
Unified authentication using your GPG identity
Better key lifecycle management with subkey capabilities

Stay safe and practice good key hygiene!