How Linux Manages GnuPG Keyrings

In Linux, GNU Privacy Guard (GnuPG or GPG) manages public and private cryptographic keys through dedicated keyrings stored in user-specific directories to facilitate file encryption, decryption, and digital signing. This article provides a comprehensive technical overview of how modern Linux distributions store, structure, and access these keyrings, the interaction between the file system and background daemons like gpg-agent, and the step-by-step cryptographic workflows executed when protecting or authenticating files.

The Keyring Storage Architecture

Modern Linux systems running GnuPG version 2.1 and later store user keyrings by default in the hidden directory ~/.gnupg/. The operating system enforces strict file permissions (typically 0700 for the directory and 0600 for the files within) to restrict access strictly to the owner.

The internal architecture separates public and private key material:

• Public Keys (pubring.kbx): Public keys are stored in a database format known as Keybox (.kbx). This format supports faster searches and indexing compared to legacy OpenPGP formats. It maintains imported public certificates from external users, as well as your own public keys.
• Private Keys (private-keys-v1.d/): Rather than keeping all secret keys in a monolithic secring.gpg file (the legacy approach), modern GnuPG stores each private key as an individual, encrypted S-expression file inside the private-keys-v1.d subdirectory. Each file is named after the key's internal keygrip (a SHA-1 hash of the key parameters).
• Trust Database (trustdb.gpg): Tracks the user's Web of Trust, recording trust assignments given to various key owners.

The Role of gpg-agent

Linux manages the decryption and usage of private keys through a daemon called gpg-agent. When GnuPG operations require a private key, the gpg command does not read the raw private key file directly. Instead:

1. The client connects to gpg-agent through a local UNIX domain socket located in /run/user/<UID>/gnupg/.
2. gpg-agent handles key unlocking, prompting the user for a passphrase via a Pinentry pin dialog if the key is not already cached in memory.
3. The agent signs or decrypts data directly and hands the result back to the GnuPG process, ensuring that the unencrypted private key never leaves the agent's memory space.

Encrypting and Decrypting Files

Keyrings act as the local reference point for asymmetric encryption operations:

• Encryption (gpg --encrypt): When encrypting a file for a recipient, GnuPG searches pubring.kbx for the recipient's identifier (Key ID, fingerprint, or email). GnuPG generates a random symmetric session key, encrypts the file's contents using a symmetric cipher (such as AES-256), and encrypts the session key using the recipient's public key fetched from the keyring.
• Decryption (gpg --decrypt): GnuPG reads the encrypted file package to identify which key ID was used for encryption. It delegates the task to gpg-agent, which looks for the corresponding keygrip inside private-keys-v1.d/. Once the user enters the passphrase, the agent decrypts the session key, and GnuPG decrypts the underlying payload.

Signing and Verifying Files

Digital signatures verify authenticity and integrity using the same keyring ecosystem:

• Signing (gpg --sign or gpg --detach-sign): To sign a file, GnuPG computes a cryptographic hash (such as SHA-256 or SHA-512) of the file content. It sends this hash to gpg-agent, which uses the user’s secret key to create a signature block containing the encrypted hash and metadata.
• Verification (gpg --verify): When verifying a signature, GnuPG checks pubring.kbx for the signer's public key. If present, it uses that public key to validate the signature against the file’s current hash. GnuPG then queries trustdb.gpg to determine whether the signer's identity has been validated by the local user, warning the user if the signature is mathematically valid but belongs to an untrusted or unverified key.

Interacting with Keyrings via the CLI

Linux allows direct administration of keyrings using standard shell commands:

• Viewing Keys: gpg --list-keys reads pubring.kbx to display public keys, and gpg --list-secret-keys queries the agent and key directory to display available private keys.
• Importing Keys: gpg --import keyfile.asc integrates external public or private keys into their respective formats in ~/.gnupg/.
• Exporting Keys: gpg --armor --export [UID] extracts a public key from pubring.kbx into an ASCII-armored format for distribution.
• Deleting Keys: gpg --delete-keys [UID] removes public records from pubring.kbx, while gpg --delete-secret-keys [UID] removes private key files from private-keys-v1.d/.