oam/knowledge base/gnupg.md

GnuPG

Table of contents

1. TL;DR
2. Encryption
3. Decryption
4. Key export
5. Key import
6. Key trust
7. Unattended key generation
8. Change a key's password
9. Put comments in a message or file
10. Use GPG keys for SSH authentication
    1. Create authentication-capable keys or subkeys
    2. Enable SSH to use GPG (sub)keys
    3. Share GPG-SSH keys
11. Troubleshooting
    1. gpg failed to sign the data; fatal: failed to write commit object
    2. sign_and_send_pubkey: signing failed for … from agent: agent refused operation
    3. New configuration settings are ineffective
12. Further readings
13. Sources

TL;DR

# Install on Mac OS X.
# Choose one.
brew install --cask 'gpg-suite-no-mail'
brew install 'gnupg' 'pinentry-mac'

# Launch components.
gpgconf --launch
gpgconf --launch 'gpg-agent'

# Reload components.
gpgconf -R
gpgconf --reload 'gpg-agent'

# Kill components.
gpgconf -K 'all'
gpgconf --kill 'gpg-agent'

# FIXME
gpg-connect-agent updatestartuptty /bye
gpg-connect-agent reloadagent '/bye'


# List existing keys.
gpg -k
gpg --list-keys --keyid-format 'short'
gpg -K --with-subkey-fingerprint
gpg --list-secret-keys --with-keygrip --keyid-format '0xlong'

# Generate new keys.
gpg --gen-key
gpg --generate-key
gpg --full-generate-key
gpg --expert --full-generate-key

# Generate new key in an unattended way.
# The non-interactive (--batch) option requires a settings file.
gpg --generate-key --batch 'setting.txt'
gpg --generate-key --batch <<-EOF
…
EOF

# Import keys from files.
gpg --import 'keys.asc'

# Export keys to files.
gpg -a --export > 'all.public-keys.asc'
gpg --armor --export -o 'given.public-key.asc' 'key_fingerprint'
gpg -a --export-secret-keys --output 'all.private-keys.asc'
gpg -a --export-secret-subkeys 'subkey_fingerprint'! > 'given.private-subkey.asc'

# Delete keys from the keyring.
# The non-interactive (--batch) option requires the key fingerprint.
gpg --delete-secret-key 'recipient'
gpg --delete-key 'recipient'
gpg --delete-keys --batch 'key_fingerprint'

# Get keys' fingerprint information.
gpg --fingerprint
gpg --fingerprint 'recipient'

# Change keys' expiration date.
# Use '0', 'never' or 'none' as expiration period to disable expiration.
# Use '*' as subkey fingerprint to set the expiration date of all non-revoked
# subkeys.
gpg --quick-set-expire 'key_fingerprint' '0'
gpg --quick-set-expire 'key_fingerprint' '2085-11-24'
gpg --quick-set-expire 'key_fingerprint' '20241101T203012' 'subkey_fingerprint'
gpg --quick-set-expire 'key_fingerprint' '1y' '*'

# Generate revoking certificates.
# To actually revoke the key, merge it with the certificate using '--import'.
# Use the '--edit' command to only revoke a subkey or a key signature.
gpg --gen-revoke
gpg --generate-revocation -ao 'revoke.cert' 'fingerprint'

# Change keys' passphrase.
# Use '--dry-run' to just check the current password is correct.
gpg --passwd 'fingerprint'
gpg --change-passphrase --dry-run 'recipient'


# Encrypt files *a*symmetrically.
gpg -o 'file.out.gpg' -r 'recipient' -e 'file.in'
gpg -o 'file.out.gpg' -u 'sender' -r 'recipient' --encrypt 'file.in'
gpg --encrypt-files --batch -r 'recipient' 'file.in.1' 'file.in.N'
gpg -e --multifile --batch -r 'recipient' --yes 'file.in.1' 'file.in.N'

# Encrypt files *symmetrically*.
# Simply encrypts data with a passphrase.
gpg -c 'input.file'
gpg --symmetric --s2k-cipher-algo 'AES256' --s2k-digest-algo 'SHA512' \
  --s2k-count '65536' 'input.file'

# Encrypt files for multiple recipients.
gpg -e … -r 'recipient_1' -r 'key_fingerprint' -r 'recipient_N'

# Decrypt files.
gpg -d 'file.gpg'
gpg -o 'file.out' --decrypt 'file.in.gpg'
gpg --decrypt-files --batch 'file.in.gpg.1' 'file.in.gpg.N'
gpg -d --multifile --batch --yes 'file.in.gpg.1' 'file.in.gpg.N'

# Encrypt directories.
gpgtar -o 'dir.tar.gpg' -c 'input/dir'

# Decrypt directories.
gpgtar -d 'dir.tar.gpg'
gpgtar -o 'dir' -d 'dir.tar.gpg'


# Get the short ID of the signing key only for a user.
# Primarily usable for git's signingKey configuration.
gpg --list-keys --keyid-format 'short' 'recipient' \
| grep --extended-regexp '^pub[[:blank:]]+[[:alnum:]]+/[[:alnum:]]+[[:blank:]].*\[[[:upper:]]*S[[:upper:]]*\]' \
| awk '{print $2}' \
| cut -d '/' -f 2


# Integrate with the SSH agent.
export SSH_AUTH_SOCK="$(gpgconf --list-dirs 'agent-ssh-socket')" && \
gpgconf --launch 'gpg-agent'

# Export keys in OpenSSH format.
gpg --export-ssh-key 'key_identifier'
gpg --export-ssh-key 'ed25519_key' > ~'/.ssh/id_ed25519.pub'


# Integrate with Pinentry.
export GPG_TTY="$(tty)"

Encryption

# Single file.
gpg --output 'file.out.gpg' --encrypt --recipient 'recipient' 'file.in'
gpg --armor --symmetric --output 'file.out.gpg' 'file.in'

# All files found.
find . -type 'f' -name 'secret.txt' \
  -exec gpg --batch --yes --encrypt-files --recipient 'recipient' {} ';'

Decryption

# Single file.
gpg -d 'file.gpg'
gpg --output 'file.out' --decrypt 'file.in.gpg'

# All files found.
find . -type f -name "*.gpg" -exec gpg --decrypt-files {} +

The second command will create the decrypted version of all files in the same directory. Each file will have the same name of the encrypted version, minus the .gpg extension.

Key export

As the original user, export all public keys to a base64-encoded text file and create an encrypted version of that file:

# Export.
gpg --armor --export > 'all.public-keys.asc'
gpg --armor --export 'recipient' > 'recipient.public-keys.asc'

# Encryption.
gpg --output 'file.out.gpg' --encrypt --recipient 'recipient' 'file.in'
gpg --armor --symmetric --output 'file.out.gpg' 'file.in'

Export all encrypted private keys (which will also include corresponding public keys) to a text file and create an encrypted version of that file:

# Export.
gpg --armor --export-secret-keys > 'all.private-keys.asc'
gpg --armor --export-secret-keys 'recipient' > 'recipient.private-keys.asc'

# Encryption.
gpg --output 'file.out.gpg' --encrypt --recipient 'recipient' 'file.in'
gpg --armor --symmetric --output 'file.out.gpg' 'file.in'

Optionally, also export gpg's trustdb to a text file:

gpg --export-ownertrust > 'otrust.txt'

Key import

As the new user execute gpg --import commands against the secured files, or the decrypted content of those files, and then check for the new keys with gpg -k and gpg -K, e.g.:

gpg --output 'myprivatekeys.asc' --decrypt 'mysecretatedprivatekeys.sec.asc' && \
gpg --import 'myprivatekeys.asc'
gpg --output 'mypubkeys.asc' --decrypt 'mysecretatedpubkeys.sec.asc'
gpg --import 'mypubkeys.asc'
gpg --list-secret-keys
gpg --list-keys

Optionally import the trustdb file as well:

gpg --import-ownertrust 'otrust.txt'

Key trust

$ gpg --edit-key 'key_fingerprint'
gpg> trust
gpg> quit

Unattended key generation

The non-interactive (--batch) option requires a settings file.

# basic key with default values
gpg --batch --generate-key <<EOF
    %echo Generating a default key
    Key-Type: default
    Subkey-Type: default
    Name-Real: Joe Tester
    Name-Comment: with stupid passphrase
    Name-Email: joe@foo.bar
    Expire-Date: 0
    Passphrase: abc
    # Do a commit here, so that we can later print "done" :-)
    %commit
    %echo done
EOF

Change a key's password

$ gpg --edit-key 'key_fingerprint'
gpg> passwd
gpg> quit

Put comments in a message or file

One can put comments in an armored ASCII message or key block using the Comment keyword for each line:

-----BEGIN PGP MESSAGE-----
Comment: …
Comment: …

hQIMAwbYc…
-----END PGP MESSAGE-----

OpenPGP defines all text to be in UTF-8, so a comment may be any UTF-8 string.
The whole point of armoring, however, is to provide seven-bit-clean data, so if a comment has characters that are outside the US-ASCII range of UTF they may very well not survive transport.

Use GPG keys for SSH authentication

See also How to enable SSH access using a GPG key for authentication.

This exercise will use a GPG subkey with only the authentication capability enabled to complete SSH connections.
You can create multiple subkeys as you would do for SSH key pairs.

Create authentication-capable keys or subkeys

To create subkeys, you should already have a GPG key. If you don't, read one of the many fine tutorials available on this topic.
Create the subkey by editing your existing key in expert mode to get access to the appropriate options:

$ gpg --expert --edit-key 'key_fingerprint'
gpg> addkey
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

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? s
Your selection? e
Your selection? a

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

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

Your selection? q
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (4096)
Requested keysize is 4096 bits
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)
Key does not expire at all
Is this correct? (y/N) y
Really create? (y/N) y

sec  rsa2048/8715AF32191DB135
     created: 2019-03-21  expires: 2021-03-20  usage: SC
     trust: ultimate      validity: ultimate
ssb  rsa2048/150F16909B9AA603
     created: 2019-03-21  expires: 2021-03-20  usage: E
ssb  rsa4096/17E7403F18CB1123
     created: 2019-03-21  expires: never       usage: A
[ultimate] (1). Johnny B. Good

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

Enable SSH to use GPG (sub)keys

When using SSH, ssh-agent is used to manage SSH keys. When using a GPG key, gpg-agent is used to manage GPG keys.
To get gpg-agent to handle requests from SSH, you need to enable its SSH support:

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

You can avoid using ssh-add to load the keys by preemptively specifying which GPG keys to use in the ~/.gnupg/sshcontrol file.
Entries in this file need to be keygrips (internal identifiers that gpg-agent uses to refer to the keys). A keygrip refers to both the public and private key.
Find the keygrips you need, then add them to the ~/.gnupg/sshcontrol file:

$ gpg -K --with-keygrip
/home/jbgood/.gnupg/pubring.kbx
-----------------------------
sec   rsa4096 2017-11-13 [SC] [expires: 2025-11-12]
      7425E11D898C449FDD3D1B4A7E747A8618CB109F
      Keygrip = E045864F555B3432E6DFCA2EF7ED47403A6E399C
uid           [ultimate] Johnny B. Good <j.b.good@email.com>
uid           [ultimate] Johnny <johnny@mymail.com>
ssb   rsa4096 2018-01-03 [E]
      Keygrip = B4674D4429AE049663BE4FEF9407C6B90F7AF122
ssb   rsa4096 2018-05-04 [A]
      Keygrip = B3D630644D14A452502A84FB09E5257CF54C3E04

sec   rsa4096 2022-01-03 [SCEA] [expires: 2025-01-02]
      8B6DC0BF4D73373C2A529C65CC54F9AC6E542DE7
      Keygrip = 03CE1FCE255AC0BB747BBBF61C9B8378CF78A2FC
uid           [ unknown] Luna Varasi <luna.var@example.com>

$ echo 'B3D630644D14A452502A84FB09E5257CF54C3E04' >> ~'/.gnupg/sshcontrol'
$ echo '03CE1FCE255AC0BB747BBBF61C9B8378CF78A2FC' >> ~'/.gnupg/sshcontrol'

Now tell SSH how to access gpg-agent by setting the value of the SSH_AUTH_SOCK environment variable.
Alternatively, and for a more permanent solution, set the option in the .ssh/config file:

export SSH_AUTH_SOCK=$(gpgconf --list-dirs 'agent-ssh-socket')

# alternative
echo "\nIdentityAgent $(gpgconf --list-dirs 'agent-ssh-socket')" \
| tee -a ~'/.ssh/config'

Now you can launch the gpg agent:

gpgconf --launch gpg-agent

Check the key has been imported correctly:

$ gpg --export-ssh-key 'Johnny B. Good'
ssh-rsa AAAAB3NzaC…7SD8UQ== openpgp:0x7BB65DA2
$ ssh-add -L
ssh-rsa AAAAB3NzaC…7SD8UQ== (none)

Share GPG-SSH keys

Run ssh-add -L to list one's public keys, then copy them over manually to the remote host.
Alternatively, use ssh-copy-id as one would normally do.

Troubleshooting

gpg failed to sign the data; fatal: failed to write commit object

Context:

• git is instructed to sign a commit with gpg.

• git commit fails with the following error:

  gpg failed to sign the data
  fatal: failed to write commit object
  

• Pinentry should have prompted to input the key's passphrase, but the prompt did not appear.

Cause:

The environment variable GPG_TTY was not set and Pinentry could not reach the terminal session to prompt for the key's passphrase.

Solution:

Make sure the environment variable GPG_TTY is set to the current TTY:

export GPG_TTY=$(tty)

sign_and_send_pubkey: signing failed for … from agent: agent refused operation

Context:

• git pull fails with the following error:

  sign_and_send_pubkey: signing failed for … from agent: agent refused operation
  user@git.server.fqdn: Permission denied (publickey).
  fatal: Could not read from remote repository.
  

• The repository is configured to connect to the remote using SSH.

• ssh is instructed to use a GPG key for authentication.

• Said GPG key is accepted for the user on the Git server.

• Pinentry should have prompted to input the key's passphrase, but the prompt did not appear.

Solution:

• Make sure the environment variable GPG_TTY is set to the current TTY:

  export GPG_TTY=$(tty)
  

• Reload the GPG agent for good measure:

  gpg-connect-agent reloadagent '/bye'
  

New configuration settings are ineffective

Cause:

If already running, the GPG agent is still using the old configuration.
Changing the configuration file now will have no effect.

Solution:

Reload the GPG agent:

gpg-connect-agent reloadagent '/bye'

Further readings

• Commonly seen problems
• Unattended key generation
• OpenPGP best practices
• GNU/Linux crypto series

Sources

All the references in the further readings section, plus the following:

• Decrypt multiple openpgp files in a directory
• ask redhat
• how can i remove the passphrase from a gpg2 private key?
• How to enable SSH access using a GPG key for authentication
• gpg failed to sign the data fatal: failed to write commit object
• Can you manually add a comment to a PGP public key block and not break it?
• How to renew a (soon to be) expired GPG key
• Renew GPG key
• Archlinux's GnuPG wiki page
• GPG agent for SSH authentication
• Modify .gnupg home directories