Handling GnuPG keyrings

This page contains general hints about building and updating sets of GnuPG keys for uploading them to Savannah.

For the user, two forms of GnuPG key sets exist,

  • exported in a file
  • imported in a GnuPG home directory

GnuPG can only edit keys in a home directory. GnuPG provides two ways to select the home directory to operate on, the --homedir option and the GNUPGHOME environment variable. This page will use the former.

Downloading the current keyring

This is how you can get the current keyring of a group (where group is the 'unix group name'),

wget --content-disposition \
  'https://savannah.gnu.org/p/release-gpgkeys.php?group=group&download=1'

The command saves the keyring in a file named group-keyring.gpg.

You can list the downloaded keys with the gpg --show-keys command,

gpg --show-keys group-keyring.gpg

Creating a fresh GnuPG home directory

Usually, the default home directory contains all keys used for your everyday work. Many of them may have signatures, user IDs or subkeys you want to omit in the resulting keyring, or they may be completely unrelated to the keyring in question, so it's convenient to use a separate home directory for editing the keyring.

In order to make it, just create a new directory denying with the access restricted to the owner:

mkdir -m og= keyring

GnuPG will detect an empty directory and automatically initialize it when first invoked on it.

Generating a new keypair

In short, gpg --generate-key and stick to the defaults. This will create a secret key needed to make signatures and decrypt messages encrypted to it, so a non-temporary home directory should be used, like the GnuPG default (~/.gnupg).

Importing keys

Import the old keyring first,

gpg --homedir keyring --import old-keyring.gpg

Here old-keyring.gpg is the file containing the previous revision of the keyring.

Then, you can import more keys if needed,

gpg --homedir keyring --import new-keys.gpg

You can import keys from multiple files at once,

gpg --homedir keyring --import old-keyring.gpg new-keys.gpg

When all files have the same format (ASCII or binary), you can even concatenate them,

cat old-keyring.gpg new-keys.gpg | gpg --homedir keyring --import -

Selecting keys

When listing, deleting, editing and exporting keys, gpg accepts key specifications in forms of:

  • 40-digit hexadecimal key fingerprint,
  • last 8 or last 16 digits of the fingerprint,
  • part of the user ID (case-insensitive),
  • other forms like keygrips.

Listing keys

gpg --homedir keyring --list-keys [key...]

When no keys are specified, all keys in the home directory are listed.

Deleting keys

gpg --homedir keyring --delete-keys key [another_key...]

GnuPG will ask for confirmation.

Editing keys

GnuPG lets edit existing keys interactively with the --edit-key command. Operations like extending the expiry date, adding user IDs, subkeys, signatures require a secret key, so you may want to specify a different working directory that contains it. After that, you can export the key, import it in the temporary directory and edit the key there to remove the data that shouldn't come into the final keyring.

gpg --homedir keyring --edit-key key

The most useful commands in the --edit-key menu are help, uid, key, delsig, deluid, delkey, sign, expire, clean, minimize, save.

When extending the expiry dates, be sure to extend both the date of the primary key and all subkeys that should be usable. A simple way not to forget about extending the dates of the subkeys is to make them never expire---the expiry date of the primary key will still limit their usage.

Exporting keys

gpg --homedir keyring --armor --export [key...] > new-keyring.asc

When no keys are specified, all keys from the home directory are exported.

Note the --armor option. It makes GnuPG export in the ASCII format; by default, the format is binary. The binary format has two disadvantages.

First, it's harder to copy and paste into the browser without unintentional corruption.

Then, the ASCII format allows using a plain text editor to join a few sub-keyrings interleaved with comments in a free form, and even with a signed GnuPG message, like

Totally historical keys.
-----BEGIN PGP PUBLIC KEY BLOCK-----

mQENBFr1PisBCAC9xQcWyOZRLa6K2g7NJbvQmm7p89/xifFYXPpMTQAnlSoCtUdZ
...
=hZua
-----END PGP PUBLIC KEY BLOCK-----

J.R Hacker's <jrh> current key.
-----BEGIN PGP PUBLIC KEY BLOCK-----

PisBCAC9xQmQhZuaENBFm7p89/xXr1cWyOZRLa6K2g7NJblSoCtUdZvQmPpMTQAn
...
=ifFY
-----END PGP PUBLIC KEY BLOCK-----

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Keys used for releases of Foobar

0.1
39EC528A6D072CD393B0051CBDBFDE8E21107A93
...
-----BEGIN PGP SIGNATURE-----

iIYEARYKAC4WIQQQXWtqoNRQAwZOtn1mPwJRYifeRgUCaH4j+BAcYm9iQHNhdmFu
...
=buB6
-----END PGP SIGNATURE-----

When importing the keyring with the --import command, GnuPG will ignore anything outside the markers of public key blocks.

More info

Copyright © 2025 Ineiev

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.