Inspect a GnuPG Keybox Safely with kbxutil

kbxutil lets you look inside a GnuPG keybox, count its records and spot duplicates. It can also pull out selected records as a new stream, all without touching the keys GnuPG cares about. The examples use GnuPG 2.4.4 from Ubuntu package gnupg-utils 2.4.4-2ubuntu17.6. Allow about ten minutes if you already have a keybox and an OpenPGP keyblock to test.

This is mainly a diagnostic tool. The usual keybox is pubring.kbx in a GnuPG home directory. It can contain OpenPGP keys and X.509 certificates, together with the metadata and indexes GnuPG uses. Work on a copy when an operation will produce data for later replacement. Do not point an experimental command at a live keybox while GnuPG or GPGSM is using it.

1. Confirm the installed command

Check which binary is being run and record its version. This is an ordinary, read-only check and does not need elevated privileges:

$ command -v kbxutil
/usr/bin/kbxutil
$ kbxutil --version
kbxutil (GnuPG) 2.4.4
$ dpkg-query -W -f='${Package} ${Version}\n' gnupg-utils
gnupg-utils 2.4.4-2ubuntu17.6

The installed command accepts a list of files after its options. In the examples below, replace /path/to/pubring.kbx with the actual path. A common distraction is to assume that kbxutil manages GnuPG configuration or private keys: it examines keybox data, and it is not a replacement for gpg, gpgsm or the keybox daemon.

2. List the records and metadata

Start with the default operation:

$ kbxutil /path/to/pubring.kbx
BEGIN-RECORD: 0
Length: 32
Type:   Header
Version: 1
...
END-RECORD

The output is a human-readable dump. Each record is called a blob. A normal file begins with a header record, followed by records such as OpenPGP or X.509 data. The exact lengths, fingerprints, user IDs and timestamps depend on your keybox, so do not compare the sample values with your own as if they were defaults.

Checkpoint: If the command says it cannot open the file, check the path and permissions first:

$ ls -l /path/to/pubring.kbx
$ test -r /path/to/pubring.kbx && echo readable

Do not use sudo as a first response. A keybox in your own GnuPG home should normally be readable by your account. If it belongs to another account, arrange access through the normal ownership and backup process rather than changing permissions casually.

3. Get a compact record count

Use --stats when a full dump is too noisy:

$ kbxutil --stats /path/to/pubring.kbx
Total number of blobs:        2
               header:        1
               empty:         0
               openpgp:       1
               x509:          0
               non flagged:   1
               secret flagged: 0
               ephemeral flagged: 0

The spacing varies with the installed build and counts. The useful distinction is between the total, the header, OpenPGP records, X.509 records and flagged records. An ephemeral record is temporary data, not an ordinary persistent key entry. Treat the statistics as an observation of this file, not as a check that every key is usable or trusted.

4. Check for duplicate records

Run the duplicate check before investigating a suspiciously repeated key or certificate:

$ kbxutil --find-dups /path/to/pubring.kbx

No output is the useful result in the normal case. If records are reported, save the listing and inspect the keybox dump before taking action. This command identifies a data condition; it does not decide which record should be kept and it does not repair the file.

Safety boundary: Do not delete records from the live keybox based on this result. Back up the file, stop software that may be using it, and use the supported GnuPG import or removal workflow for the relevant key material. Keep the original until the replacement has been tested.

5. Extract selected records with --cut

--cut writes selected keybox records to standard output. The --from and --to values are record numbers, inclusive. In a small test keybox where record 0 is the header and record 1 is an OpenPGP record:

$ kbxutil --cut --from 1 --to 1 /path/to/pubring.kbx > /tmp/openpgp-record.kbx
$ kbxutil --stats /tmp/openpgp-record.kbx
Total number of blobs:        1
               header:        0
               empty:         0
               openpgp:       1

The extracted file is a keybox record stream, not an ASCII-armoured key export. Redirect it to a new temporary name so that the source remains untouched. Confirm the range from the normal listing first; a range that starts at the wrong record can produce a technically valid but incomplete result.

--dry-run is available when you are checking a workflow that might make changes. With --cut, output is still produced because the requested export is the result you are asking the command to inspect. Treat shell redirection as state change in your own filesystem: use a new path and check its size before moving anything into place.

6. Convert an OpenPGP keyblock into keybox records

--import-openpgp reads binary OpenPGP keyblocks and emits keybox records. For example, first create a binary export with gpg from a key you are authorised to handle:

$ gpg --export KEY_IDENTIFIER > /tmp/public-key.gpg
$ kbxutil --import-openpgp /tmp/public-key.gpg > /tmp/imported-record.kbx
$ kbxutil --stats /tmp/imported-record.kbx
Total number of blobs:        1
               header:        0
               openpgp:       1

Replace KEY_IDENTIFIER with a fingerprint or another identifier accepted by your local gpg setup. The output is binary, so do not send it to a terminal or edit it in a text editor. Use a binary export, not an ASCII-armoured file made with --armor: the installed command reports parse errors for armour.

This pipeline creates a new output file. It does not merge anything into pubring.kbx. If you need to import a key into GnuPG, use the normal gpg --import workflow after reviewing the key and its provenance. There is no undo requirement for the examples here because they only create files under /tmp; remove those temporary files after inspection if they contain material you do not need.

7. Keep failures in proportion

A missing file, an invalid record range and a malformed OpenPGP input are different failures. Re-run the read-only listing, verify the source format and capture stderr before changing a keybox. The installed command can return a non-zero status for an invalid range, but a successful status alone is not proof that the extracted data is semantically complete. Check the resulting file with --stats and, where relevant, a separate GnuPG verification or listing command.

Debugging options --debug and --debug-all can produce more diagnostic detail. Use them only when needed, and remember that debug output may expose identifiers or file details. Store it with the same care as the keybox it describes. Neither option repairs data.

Done means