Debian apt-key Deprecation: How to Add Repository Keys

The deprecation of apt-key fundamentally changes how the Debian operating system handles third-party package signatures, replacing a centralized, vulnerable trust store with isolated, repository-specific key management. Historically, adding a signing key made it trusted for all repositories on the system, creating significant security risks. With modern Debian releases (starting with Debian 11 Bullseye and fully enforced in Debian 12 Bookworm), administrators must download armored keys, store them in dedicated keyring directories such as /etc/apt/keyrings/, and explicitly link them to their respective repositories using the signed-by option.

Why apt-key Was Deprecated

The traditional apt-key add command imported cryptographic public keys into a single global keyring located at /etc/apt/trusted.gpg (or /etc/apt/trusted.gpg.d/). Under this architecture, APT did not map specific keys to specific repositories. If you imported a third-party repository's key to install a single application, that key gained the authority to validate packages from any other repository configured on the system, including Debian's base system repositories. If a third-party repository was compromised or acted maliciously, it could sign and distribute malicious updates for critical core utilities without triggering signature verification errors.

The Modern Key Installation Standard

The modern approach isolates trust by ensuring each third-party key validates only packages originating from its specified source. This is achieved through a two-step process: storing the key file in a dedicated location and referencing it explicitly in the repository configuration.

1. Storing the GPG Key

Instead of importing keys into the global APT keyring, keys are stored as standalone files. Recommended practices place system-managed keys in /usr/share/keyrings/ and administrator-managed keys in /etc/apt/keyrings/.

Keys must typically be stored in binary OpenPGP format (ending in .gpg) rather than ASCII-armored format (ending in .asc), although modern versions of APT can handle dearmored keys directly if configured correctly.

To download, convert, and store a key in /etc/apt/keyrings/, use the following standard commands:

# Ensure the keyrings directory exists with secure permissions
sudo install -m 0755 -d /etc/apt/keyrings

# Download and dearmor the key to the destination file
curl -fsSL https://example.com/repo/KEY.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/example-repo.gpg

# Ensure read permissions for APT
sudo chmod 0644 /etc/apt/keyrings/example-repo.gpg

2. Associating the Key with the Repository

Once the key is stored, the repository configuration must point directly to it using the signed-by attribute.

Traditional One-Line Format (.list files):

In /etc/apt/sources.list.d/example.list, specify the path to the key inside square brackets:

deb [signed-by=/etc/apt/keyrings/example-repo.gpg] https://example.com/repo/ stable main

Modern Deb822 Format (.sources files):

In /etc/apt/sources.list.d/example.sources, specify the path in the Signed-By field:

Types: deb
URIs: https://example.com/repo/
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/example-repo.gpg

Summary of Changes

  • Scope of Trust: Trust is scoped strictly to individual repositories rather than globally across the entire operating system.
  • Storage Location: Keys move from /etc/apt/trusted.gpg to individual files in /etc/apt/keyrings/ or /usr/share/keyrings/.
  • Tooling: Deprecated apt-key wrappers are replaced by standard utilities like curl, wget, gpg, and install.
  • Configuration: Repository definitions explicitly dictate which GPG fingerprint or file validates their contents via the signed-by directive.