Differences between revisions 7 and 8
Revision 7 as of 2017-03-22 15:31:43
Size: 8212
Editor: TheAnarcat
Comment: add jessie exception
Revision 8 as of 2017-03-22 15:33:56
Size: 8526
Editor: TheAnarcat
Comment: add explicit examples to the jessie section
Deletions are marked like this. Additions are marked like this.
Line 145: Line 145:
As an exception, you MAY replace the above key path `/usr/share/keyrings/deriv-archive-keyring.gpg` with `/etc/apt/trusted.gpg.d/archive-keyring.gpg` and use the OpenPGP key fingerprint in the `Signed-By` option instead of the file path. As an exception, you MAY replace the above key path `/usr/share/keyrings/deriv-archive-keyring.gpg` with `/etc/apt/trusted.gpg.d/archive-keyring.gpg` and use the OpenPGP key fingerprint in the `Signed-By` option instead of the file path.   The wget command would then look like this:

{{{
wget -O /etc/apt/trusted.gpg.d/deriv-archive-keyring.gpg https://deriv.example.net/debian/deriv-archive-keyring.gpg
}}}

And the sources.list entry WOULD be:

{{{
deb [signed-by=KEYFINGERPRINT] https://deriv.example.net/debian/ deriv-testing main
}}}

Instructions to connect to a third-party repository

There are many different ways of configuring an unofficial APT repository on a machine. Those instructions aim to standardize, as much as possible, a secure and state of the art procedure to add those repositories in the idea of making UntrustedDebs generally more secure.

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 instructions for configurations of Debian 8 "jessie" repositories are shown in the examples section.

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 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

The reason why we avoid ASCII-armored files is that they cannot be used directly by SecureApt.

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.

Entries MUST be added in the /etc/apt/sources.list.d directory using the short repository name. The "Deb822" file format MAY also be used to improve clarify for complex entries.

The repository SHOULD be served over HTTPS if possible. A free X509 certificate MAY be obtained from [Let's Encrypt](https://letsencrypt.org/) and automatically configured using the certbot package.

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

deb [signed-by=/usr/share/keyrings/deriv-archive-keyring.gpg] https://deriv.example.net/debian/ deriv-testing main

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

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

Types: deb
URIs: https://deriv.example.net/debian/
Suites: deriv-testing
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).

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. ixing 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-testing.sources containing the following:

Types: deb deb-src
URIs: https://deriv.example.net/debian/
Suites: deriv-testing
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.

Jessie configurations

Debian 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: http://deriv.example.net deriv-testing InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 21E0CA38EA2EA4AB

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

The wget command would then look like this:

wget -O /etc/apt/trusted.gpg.d/deriv-archive-keyring.gpg https://deriv.example.net/debian/deriv-archive-keyring.gpg

And the sources.list entry WOULD be:

deb [signed-by=KEYFINGERPRINT] https://deriv.example.net/debian/ deriv-testing main


CategoryPackageManagement