11222
Comment: show an example of the gpg dance
|
11377
|
Deletions are marked like this. | Additions are marked like this. |
Line 189: | Line 189: |
* [[https://salsa.debian.org/apt-team/apt/-/merge_requests/176|support for embeddeding OpenPGP keys directly in the sources.list]] might improve on this |
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.
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.
Contents
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, sks-keyservers.net. 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 https://deriv.example.net/debian/deriv-archive-keyring.gpg
Chances are the key being distributed is 'ascii-armored'. In that case you will need to dearmor it:
curl https://deriv.example.net/debian/deriv-archive-keyring.gpg | gpg --dearmor > /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. 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] https://deriv.example.net/debian/ stable main
The above is a sources.list line for a fictitious 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 URIs: https://deriv.example.net/debian/ 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 SecureApt 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 deriv.example.net repository from upgrading already installed packages from official repositories, while allowing upgrades to be performed for the deriv repository:
Package: * Pin: origin deriv.example.net Pin-Priority: 100
Alternatively, this configuration will allow the user to install packages from the deriv repository but forbid automated upgrades:
Package: * Pin: origin deriv.example.net 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 deriv.example.net 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.
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 https://deriv.example.net/debian/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 URIs: https://deriv.example.net/debian/ 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 deriv.example.net 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.
Troubleshooting
W: GPG error: http://deriv.example.net stable InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 744ACF4DF3319FFA
This error message is commonly seen when the GPG key you are using is 'ascii-armored' instead of being in binary form.
OpenPGP key handling
APT is somewhat peculiar in how it handles OpenPGP keys. As indicated above, you MUST NOT use ascii-armored keys. If you have such a key, you should convert it to binary form with something like this:
gpg --import $KEY.asc gpg --export $KEY_FINGERPRINT > $KEY.gpg
Then $KEY.gpg can be distributed everywhere correctly.
Credits
This document was written by TheAnarcat with extensive help and review from DanielKahnGillmor.
References
DebianRepository - more documentation on Debian repositories, see in particular setup info and format info (more information about the different fields in the repository Release file)
SecureApt - OpenPGP integration in APT
SecureApt/TufDerivedImprovements - possible for the above
SourcesList - basic documentation on sources.list files
sources.list(5) - manual page
UntrustedDebs - the larger effort to make third-party repositories more secure
support for embeddeding OpenPGP keys directly in the sources.list might improve on this