Instructions to connect to a third-party repository

There are many different ways of configuring an unofficial APT repository on a machine. This document aims to standardize the procedure to add such a third-party repository to a Debian-based system so that the new repository can only ship a set of expected packages, and so that those packages will be securely delivered to the system.

Where possible, this document uses RFC-like vocabulary as defined by RFC 2119. Note that those instructions primarily target Debian 9 "stretch" or later, although we also include instructions for configuration of external repositories on a Debian 8 "jessie" system.

Note that the procedures documented here aim to prevent a repository from shipping packages that the administrator does not expect that repository to ship. For example, a repo that ships a video game emulator and its mods shouldn't be able to override libc6.

However, the installation of any single malicious package from a malicious repository can currently undo these protections, for example by running a MaintainerScripts command to override the configured preferences or by authorizing new OpenPGP keys. For the purposes of this page, attacks by a package that belongs to a given repository are out of scope. To restrict what an installed package can do, see the larger UntrustedDebs problem, and particularly Teams/Dpkg/Spec/DeclarativePackaging for a potential solution.

OpenPGP Key distribution

Repositories MUST be signed with an OpenPGP key. A binary export (gpg --export) of the key SHOULD be available at the root of the repository under the filename deriv-archive-keyring.gpg, where deriv is the a short name for the repository. The file SHOULD NOT be ascii-armored (gpg --export --armor) although a separate armored version MAY be available under deriv-archive-keyring.asc.

The key SHOULD be served over HTTPS if possible. A free X509 certificate MAY be obtained from Let's Encrypt and automatically configured using the certbot package.

The key MAY also be made available on key servers. If so, operators SHOULD choose the ad-hoc standard, This key SHOULD be signed by other keys, preferably including some that are close to the strong set, in order to leverage the OpenPGP web of trust. The key MUST be downloaded over a secure mechanism like HTTPS to a location only writable by root, which SHOULD be /usr/share/keyrings. The key MUST NOT be placed in /etc/apt/trusted.gpg.d or loaded by apt-key add.

For example, users MAY be told to run this command to download the key:

wget -O /usr/share/keyrings/deriv-archive-keyring.gpg

The reason why we avoid ASCII-armored files is that they cannot be used directly by SecureApt. We also strongly recommend the use of HTTPS as it bypasses certain MITM attacks that would allow a hostile third party to inject OpenPGP key material in the repository setup.

Sources.list entry

A sources.list entry SHOULD have the signed-by option set. This option is ignored in jessie and earlier, but should take effect in stretch and later. The signed-by entry MUST point to a file, and not a fingerprint.

The suite entry SHOULD correspond to the target Debian release if the binaries are built for a specific suite. In other cases, the suite SHOULD be the string "stable", or it MAY be a repository-specific string describing the suite concisely. If the suite does not correspond to a target Debian release, the suite naming convention MUST be clearly documented.

If the repository has no reason to be split into multiple components, then the component name SHOULD be main. If there is a reason for splitting the repo into multiple components, the reason for the split should be clearly documented (e.g. Debian's documented split) and the component names should concisely reflect that split.

Entries MUST be added in the /etc/apt/sources.list.d directory using a shortened repository name (e.g. deriv.list). The "Deb822" file format MAY be used instead to improve clarity for complex entries (e.g. deriv.sources). (See sources.list(5))

For example, this would be the content of the /etc/apt/sources.list.d/deriv.list file:

deb [signed-by=/usr/share/keyrings/deriv-archive-keyring.gpg] stable main

The above is a sources.list line for a fictive Deriv Debian derivative. The suite is stable and the component is the standard main component.

This is equivalent to the following Deb822 file format, under deriv.sources:

Types: deb
Suites: stable
Components: main
Signed-By: /usr/share/keyrings/deriv-archive-keyring.gpg

The reason we point to a file instead of a fingerprint is that the latter forces the user to add the key to the global ?AptSecure trust anchor in /etc/apt/trusted.gpg.d, which would cause the system to accept signatures from the third-party keyholder on all other repositories configured on the system that don't have a signed-by option (including the official Debian repositories).

Serving the repository under HTTPS is OPTIONAL, as it may make running a round-robin network of untrusted mirrors more difficult, and the trust chain provided by SecureApt should suffice.

Standard pinning

When a repository is added to the sources.list.d, a matching preferences file SHOULD be created to restrict the possible effects of the repository. If such a preferences file is used it MUST pin with a user-controlled label (e.g. the hostname of the URI, or some future local mark, see 858406) and MUST NOT use a field provided by the upstream Release file. The Pin-Priority field MAY be set so that packages are upgraded by default (Pin-Priority: 100) or not (Pin-Priority: 1) but it MUST NOT be set to any higher value that may lead to overwriting packages shipped with the default Debian distribution.

If no preferences file is provided or a different Pin-Priority is used, the user MUST be warned of the security consequences.

For example, this will forbid the repository from upgrading already installed packages from official repositories, while allowing upgrades to be performed for the deriv repository:

Package: *
Pin: origin
Pin-Priority: 100

Alternatively, this configuration will allow the user to install packages from the deriv repository but forbid automated upgrades:

Package: *
Pin: origin
Pin-Priority: 1

The above origin configuration has not been audited. It MAY be possible the repository could override that value. Further tests are required to confirm the above configuration is resilient to attack by the repository owner.

Note that if the local system pulls multiple repositories from the same host (e.g. different paths, different suites, or different components), then the proposed Pin: origin is incapable of distinguishing between them. Fixing this appears to require improvements in apt, see 858406.

Key rollover and updates

Keys updates SHOULD be distributed by a Debian package called deriv-archive-keyring. This package MUST distribute the key in binary form in the aforementioned location (/usr/share/keyrings/deriv-archive-keyring.gpg) and MAY also include the /etc/apt/sources.list.d/deriv.sources or /etc/apt/sources.list.d/deriv.list files and the /etc/apt/preferences.d/deriv.pref file.

If such a mechanism is used to distribute key updates, the preferences file MUST allow automatic upgrades (Pin-Priority: 100) or include a specific entry for the keyring package that adds an exception for that package:

Package: deriv-archive-keyring
Pin: origin
Pin-Priority: 100

Complete example

This example may serve as a template for instructions provided at the root of the archive to help users configure the APT repository on Debian 9 ("stretch") or later systems.

This is a Debian repository. To install packages from this repository, you should first download a trust anchor into your system using this command:

wget -O /usr/share/keyrings/deriv-archive-keyring.gpg

Then you can add the repository to your sources.list by creating a text file in /etc/apt/sources.list.d/deriv.sources containing the following:

Types: deb deb-src
Suites: stable
Architectures: i386 amd64
Components: main
Signed-By: /usr/share/keyrings/deriv-archive-keyring.gpg

Finally, you should also add the following preferences file to restrict what this repository can install, by creating the following file in /etc/apt/preferences.d/deriv.pref:

Package: *
Pin: origin
Pin-Priority: 100

Once this is done, you can run apt-get update for the changes to take effect and use apt-get install deriv-archive-keyring to make sure updates to the keyring are received in a timely manner.

Jessie configurations

Debian 8 ("jessie") critically lacks support for file-based Signed-By configurations. This means the above configuration will fail under Debian Jessie with an error like:

W: GPG error: stable InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 744ACF4DF3319FFA

As an exception, on Jessie-based systems only, you MAY replace the above key path /usr/share/keyrings/deriv-archive-keyring.gpg with /etc/apt/trusted.gpg.d/deriv-archive-keyring.gpg and use the OpenPGP fingerprint in the Signed-By option instead of the file path.

When using this configuration, the system administrator SHOULD ensure that all other repositories on the system have an explicit Signed-By option, so that the derivative's key is not capable of impersonating other archives.

The wget command would then look like this:

wget -O /etc/apt/trusted.gpg.d/deriv-archive-keyring.gpg

And the sources.list entry WOULD be:

deb [signed-by=6809F110790E0720856B562F744ACF4DF3319FFA] stable main


This document was written by TheAnarcat with extensive help and review from DanielKahnGillmor.