Skip to content

Instantly share code, notes, and snippets.

@mcattarinussi

mcattarinussi/gpg-ssh-setup.md

Last active July 19, 2025 15:54
Show Gist options
  • Save mcattarinussi/834fc4b641ff4572018d0c665e5a94d3 to your computer and use it in GitHub Desktop.
Save mcattarinussi/834fc4b641ff4572018d0c665e5a94d3 to your computer and use it in GitHub Desktop.
Download ZIP
A setup guide to use a personal gpg key for ssh authentication
Raw
gpg-ssh-setup.md

GPG - SSH setup

Generating the master key

Here we create the master key. We want only Certify capability: we use the master key only to create the subkeys, Sign - Encrypt - Authenticate capabilities will be assigned to the subkeys.

Run the following command to start the master key generation process. Select the set your own capabilities creation process (type 8)

  ▶ gpg --full-generate-key --expert
  gpg (GnuPG) 2.2.9; Copyright (C) 2018 Free Software Foundation, Inc.
  This is free software: you are free to change and redistribute it.
  There is NO WARRANTY, to the extent permitted by law.

  Please select what kind of key you want:
  (1) RSA and RSA (default)
  (2) DSA and Elgamal
  (3) DSA (sign only)
  (4) RSA (sign only)
  (7) DSA (set your own capabilities)
  (8) RSA (set your own capabilities)
  (9) ECC and ECC
  (10) ECC (sign only)
  (11) ECC (set your own capabilities)
  (13) Existing key
  Your selection? 8

Disable sign capability (type S)

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

  (S) Toggle the sign capability
  (E) Toggle the encrypt capability
  (A) Toggle the authenticate capability
  (Q) Finished

  Your selection? S

Disable encrypt capabilities (type E)

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

  (S) Toggle the sign capability
  (E) Toggle the encrypt capability
  (A) Toggle the authenticate capability
  (Q) Finished

  Your selection? E

Quit and continue the creation process (type Q)

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

  (S) Toggle the sign capability
  (E) Toggle the encrypt capability
  (A) Toggle the authenticate capability
  (Q) Finished

  Your selection? Q

Input the desired key size of the master key

  RSA keys may be between 1024 and 4096 bits long.
  What keysize do you want? (2048) 4096
  Requested keysize is 4096 bits

Setup the expiration for the master key

  Please specify how long the key should be valid.
        0 = key does not expire
        <n>  = key expires in n days
        <n>w = key expires in n weeks
        <n>m = key expires in n months
        <n>y = key expires in n years
  Key is valid for? (0) 1y
  Key expires at Sat Jul 27 17:59:59 2019 BST
  Is this correct? (y/N) y

Construct your user ID (input your full name and email, leave comment empty). Type O to complete

  GnuPG needs to construct a user ID to identify your key.

  Real name: Mattia Cattarinussi
  Email address: [email protected]
  Comment:
  You selected this USER-ID:
  "Mattia Cattarinussi <[email protected]>"

  Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O

Enter a passphrase for your master key

  ┌──────────────────────────────────────────────────────┐
  │ Please enter the passphrase to                       │
  │ protect your new key                                 │
  │                                                      │
  │ Passphrase: ________________________________________ │
  │                                                      │
  │       <OK>                              <Cancel>     │
  └──────────────────────────────────────────────────────┘

If you did the above steps correctly you should have the following result

  We need to generate a lot of random bytes. It is a good idea to perform
  some other action (type on the keyboard, move the mouse, utilize the
  disks) during the prime generation; this gives the random number
  generator a better chance to gain enough entropy.
  gpg: key 4EF9EF4CDBD7AB1B marked as ultimately trusted
  gpg: revocation certificate stored as '/Users/mattiacattarinussi/.gnupg/openpgp-revocs.d/F8DD1C85581AB87675EF97444EF9EF4CDBD7AB1B.rev'
  public and secret key created and signed.

  pub   rsa4096 2018-07-27 [C] [expires: 2019-07-27]
        F8DD1C85581AB87675EF97444EF9EF4CDBD7AB1B
  uid                      Mattia Cattarinussi <[email protected]>

Store the revocation certificate (created by gpg) for your master key on a physical device.

Generate Sign, Encrypt and Authentication subkeys

Run this command to edit your key

  ▶ gpg --expert --edit-key mattia
  gpg (GnuPG) 2.2.9; Copyright (C) 2018 Free Software Foundation, Inc.
  This is free software: you are free to change and redistribute it.
  There is NO WARRANTY, to the extent permitted by law.

  Secret key is available.

  sec  rsa4096/4EF9EF4CDBD7AB1B
  created: 2018-07-27  expires: 2019-07-27  usage: C
  trust: ultimate      validity: ultimate
  [ultimate] (1). Mattia Cattarinussi <[email protected]>

In the gpg console prompt specify that you want to add a new key for that master key:

  gpg> addkey

Select the set your own capabilities creation process (type 8)

  Please select what kind of key you want:
  (3) DSA (sign only)
  (4) RSA (sign only)
  (5) Elgamal (encrypt only)
  (6) RSA (encrypt only)
  (7) DSA (set your own capabilities)
  (8) RSA (set your own capabilities)
  (10) ECC (sign only)
  (11) ECC (set your own capabilities)
  (12) ECC (encrypt only)
  (13) Existing key
  Your selection? 8

Add Authenticate capabilities (type A). Sign and Encrypt capabilities are already enabled by default

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

  (S) Toggle the sign capability
  (E) Toggle the encrypt capability
  (A) Toggle the authenticate capability
  (Q) Finished

  Your selection? A

Type Q to continue the process

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

  (S) Toggle the sign capability
  (E) Toggle the encrypt capability
  (A) Toggle the authenticate capability
  (Q) Finished

  Your selection? Q

Input the desired key size for the subkey

  RSA keys may be between 1024 and 4096 bits long.
  What keysize do you want? (2048) 4096
  Requested keysize is 4096 bits

Setup the expiration for the subkey

  Please specify how long the key should be valid.
        0 = key does not expire
        <n>  = key expires in n days
        <n>w = key expires in n weeks
        <n>m = key expires in n months
        <n>y = key expires in n years
  Key is valid for? (0) 1y
  Key expires at Sat Jul 27 18:19:38 2019 BST
  Is this correct? (y/N) y
  Really create? (y/N) y

Input the passphrase for the master key (the one you setup in the master key generation process). You should get this result

  We need to generate a lot of random bytes. It is a good idea to perform
  some other action (type on the keyboard, move the mouse, utilize the
  disks) during the prime generation; this gives the random number
  generator a better chance to gain enough entropy.

  sec  rsa4096/4EF9EF4CDBD7AB1B
  created: 2018-07-27  expires: 2019-07-27  usage: C
  trust: ultimate      validity: ultimate
  ssb  rsa4096/855B567AA2E43D00
  created: 2018-07-27  expires: 2019-07-27  usage: SEA
  [ultimate] (1). Mattia Cattarinussi <[email protected]>

Save and exit

  gpg> save

Now if you list your keys you will see also a subkey (sub) with SEA capabilities (Sign - Encrypt - Authenticate)

  ▶ gpg --list-keys
  /Users/mattiacattarinussi/.gnupg/pubring.kbx
  --------------------------------------------
  pub   rsa4096 2018-07-27 [C] [expires: 2019-07-27]
        F8DD1C85581AB87675EF97444EF9EF4CDBD7AB1B
  uid           [ultimate] Mattia Cattarinussi <[email protected]>
  sub   rsa4096 2018-07-27 [SEA] [expires: 2019-07-27]

Setup the gpg-agent for SSH authentication

Enable the gpg-agent ssh support

  ▶ echo enable-ssh-support >> $HOME/.gnupg/gpg-agent.conf

Set SSH_AUTH_SOCK so that SSH will use gpg-agent instead of ssh-agent. Add this to tour bashprofile or zshrc

unset SSH_AGENT_PID
if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne $$ ]; then
  export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
fi
export GPG_TTY=$(tty)
gpg-connect-agent updatestartuptty /bye >/dev/null

Enable the gpg subkey for ssh authentication:

  • Get the subkey keygrip

    ▶ gpg --list-keys --with-keygrip

/Users/mattiacattarinussi/.gnupg/pubring.kbx
--------------------------------------------
pub   rsa4096 2018-07-27 [C] [expires: 2019-07-27]
      F8DD1C85581AB87675EF97444EF9EF4CDBD7AB1B
      Keygrip = 22DBE374608C6220B321D3A2543F3806FF63A49D
uid           [ultimate] Mattia Cattarinussi <[email protected]>
sub   rsa4096 2018-07-27 [SEA] [expires: 2019-07-27]
      Keygrip = A55719832AF939C531BACFFABB2A47B52FFBBF43

  • Add the keygrip of your subkey in the list of approved keys

    ▶ echo A55719832AF939C531BACFFABB2A47B52FFBBF43 >> ~/.gnupg/sshcontrol

Check if the key is present in the ssh identities list

  ▶ ssh-add -l
  4096 SHA256:bCVzkgaoGSqJC89hZ/8gclTn7ENN/dJ+mZBBw2zJFuI (none) (RSA)

Retrieve the public ssh key for the subkey

  ▶ gpg --export-ssh-key mattia
  ssh-rsa <A_LOT_OF_STUFF_HERE> openpgp:0xA2E43D00

You can test if the key is working with your Github account. The ssh public key generated in the previous step has to be added to your Github SSH keys.

  ▶ ssh -T [email protected]
  Hi mcattarinussi! You've successfully authenticated, but GitHub does not provide shell access.

Backup keys and remove the master key

Export the secret master key

  ▶ gpg -a --export-secret-keys > master-secret-key.gpg

Export all the secret subkeys

  ▶ gpg -a --export-secret-subkeys > sub-secret-keys.gpg

Save master-secret-key.gpg and sub-secret-keys.gpg on a physical device.

Delete the secret keys (you need to delete all the subkeys as well)

  ▶ gpg --delete-secret-key mattia

Enter the master password and confirm the deletion in the subsequent confirmation dialogs.

Restore the subkeys

  ▶ gpg --import sub-secret-keys.gpg

Check the result

  ▶ gpg --list-secret-keys
  /Users/mattiacattarinussi/.gnupg/pubring.kbx
  --------------------------------------------
  sec#  rsa4096 2018-09-14 [C] [expires: 2020-09-13]
        5615F7C581E8450E34F9031703426E5D827D6A81
  uid           [ultimate] Mattia Cattarinussi <[email protected]>
  ssb   rsa4096 2018-09-14 [S] [expires: 2018-09-16]
  ssb   rsa4096 2018-09-14 [E] [expires: 2020-09-13]
  ssb   rsa4096 2018-09-14 [A] [expires: 2020-09-13]

The # after the master key means that the key is not stored locally.

References

@matt-152
Copy link

FIX: sign_and_send_pubkey: signing failed for RSA from agent: agent refused operation

Wanted to add this for anyone who experienced the same issue as me. I'm using tmux on OS X.

You might attempt to SSH and get the following error:

~ % ssh -T [email protected]
sign_and_send_pubkey: signing failed for RSA "(none)" from agent: agent refused operation
[email protected]: Permission denied (publickey).

If you do, the first step is to enable logging in your .gnupg/gpg-agent.conf:

log-file /tmp/gpg-agent.log
verbose
debug all
debug-level advanced

Restart the agent (gpgconf --kill gpg-agent && gpgconf --launch gpg-agent) and try SSHing again. Now examine /tmp/gpg-agent.log

If you see this line:

2025-06-22 22:28:05 gpg-agent[16218] ssh sign request failed: Inappropriate ioctl for device <Pinentry>

It means the pinentry program you're using can't work over a tty. This likely means you're using pinentry-curses, which (I think) is the default.

You might first try using pinentry-tty. Add this line to your gpg-agent.conf:

pinentry-program <PATH_TO>/pinentry-curses # Run `which pinentry-tty` if you're not sure

Restart the agent and try again. If it still doesn't work, and you see this line in /tmp/gpg-agent.log:

2025-06-22 22:36:13 gpg-agent[16277] ssh sign request failed: Operation cancelled <Pinentry>

It means pinentry-tty isn't able to find the right tty to send the output to.

This only seems to be an issue when using gpg as an ssh-agent. I find that either option seems to work fine using gpg like normal for --signing, --encrypting, etc.

The only workaround I've found is to hook pinentry-tty with a custom shell script.

Open a new file (MAKE SURE YOU USE LIMITED PERMISSIONS!) and put this in:

#!/usr/bin/env bash
pinentry-tty -T "$(<TTY_CMD>)" "$@"

Where TTY_CMD depends on your setup. If you're using tmux like me, I found this works: tmux display -p '#{pane_tty}'

Run chmod +x <YOUR_FILE> to make it executable and edit your gpg-agent.conf to point to it:

pinentry-program <PATH_TO>/<YOUR_FILE>

SSH should work now. If so, you can remove the logging you added in earlier.

@gardenappl
Copy link

gardenappl commented Jul 16, 2025 •
edited
Loading

One thing I'd add is, if you have existing configuration in .ssh/config, GPG will actually try to read it, and this might conflict with the attempted new configuration. So I'd recommend deleting it.

Alternatively you can modify the existing SSH config by removing any IdentityFile lines and pointing them to the exported public keys from GPG. E.g.

gpg --export-ssh-key key > ~/.ssh/id_gpg.pub

Then modify .ssh/config:

Host example.com
        IdentityFile ~/.ssh/id_gpg.pub
        IdentitiesOnly yes

In theory this might work if you need multiple keys for different hosts, but I have not tested that. If you only have one key for SSH, and don't need any further configuration, then you can just delete the config and GPG will pick that one key for everything.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment