From 002b1bc46b18e9d309d337ddb15a6ccdfb6c9dde Mon Sep 17 00:00:00 2001 From: David Kalnischkies Date: Thu, 15 Oct 2015 09:35:52 +0200 Subject: refer to apt-secure(8) in unsecure repositories warning The manpage is also slightly updated to work better as a central hub to push people from all angles into the right directions without writting a book disguised as an error message. --- doc/apt-key.8.xml | 15 ++++++--- doc/apt-secure.8.xml | 87 ++++++++++++++++++++++++++++++++-------------------- 2 files changed, 64 insertions(+), 38 deletions(-) (limited to 'doc') diff --git a/doc/apt-key.8.xml b/doc/apt-key.8.xml index 1d91790ea..41628aff6 100644 --- a/doc/apt-key.8.xml +++ b/doc/apt-key.8.xml @@ -48,7 +48,11 @@ &synopsis-param-filename; or if the filename is - from standard input. - + + It is critical that keys added manually via apt-key are + verified to belong to the owner of the repositories they claim to be for + otherwise the &apt-secure; infrastructure is completely undermined. + @@ -110,10 +114,11 @@ - - Pass advanced options to gpg. With adv --recv-key you can download the - public key. - + Pass advanced options to gpg. With adv --recv-key you + can e.g. download key from keyservers directly into the the trusted set of + keys. Note that there are no checks performed, so it is + easy to completely undermine the &apt-secure; infrastructure if used without + care. diff --git a/doc/apt-secure.8.xml b/doc/apt-secure.8.xml index e343b86ea..9b4b7378d 100644 --- a/doc/apt-secure.8.xml +++ b/doc/apt-secure.8.xml @@ -13,7 +13,7 @@ &apt-email; &apt-product; - 2012-06-09T00:00:00Z + 2015-10-14T00:00:00Z @@ -45,32 +45,38 @@ Description - Starting with version 0.6, apt contains code - that does signature checking of the Release file for all - archives. This ensures that packages in the archive can't be - modified by people who have no access to the Release file signing - key. + Starting with version 0.6, APT contains code that does + signature checking of the Release file for all repositories. This ensures + that data like packages in the archive can't be modified by people who + have no access to the Release file signing key. - If a package comes from a archive without a signature, or with a - signature that apt does not have a key for, that package is - considered untrusted, and installing it will result in a big - warning. apt-get will currently only warn - for unsigned archives; future releases might force all sources - to be verified before downloading packages from them. + If an archive doesn't have a signed Release file or no Release file at all + current APT versions will raise a warning in update + operations and frontends like apt-get will require + explicit confirmation if an installation request includes a package from + such an unauthenticated archive. - The package frontends &apt-get;, &aptitude; and &synaptic; support this new - authentication feature. + In the future APT will refuse to work with unauthenticated repositories by + default until support for them is removed entirely. Users have the option to + opt-in to this behavior already by setting the configuration option + to false. + + + + Note: All APT-based package management frontends like &apt-get;, &aptitude; + and &synaptic; support this authentication feature, so this manpage uses + APT to refer to them all for simplicity only. - Trusted archives + Trusted repositories - - The chain of trust from an apt archive to the end user is made up of + + The chain of trust from an APT archive to the end user is made up of several steps. apt-secure is the last step in this chain; trusting an archive does not mean that you trust its packages not to contain malicious code, but means that you @@ -85,13 +91,14 @@ devscripts packages respectively). - The chain of trust in Debian starts when a maintainer uploads a new + The chain of trust in Debian e.g. starts when a maintainer uploads a new package or a new version of a package to the Debian archive. In order to become effective, this upload needs to be signed by a key - contained in the Debian Maintainers keyring (available in + contained in one of the Debian package maintainers keyrings (available in the debian-keyring package). Maintainers' keys are signed by other maintainers following pre-established procedures to - ensure the identity of the key holder. + ensure the identity of the key holder. Similar procedures exist in all + Debian-based distributions. @@ -132,20 +139,23 @@ However, it does not defend against a compromise of the - Debian master server itself (which signs the packages) or against a + master server itself (which signs the packages) or against a compromise of the key used to sign the Release files. In any case, this mechanism can complement a per-package signature. User configuration - apt-key is the program that manages the list - of keys used by apt. It can be used to add or remove keys, although - an installation of this release will automatically contain the - default Debian archive signing keys used in the Debian package - repositories. - - + apt-key is the program that manages the list of keys used + by APT to trust repositories. It can be used to add or remove keys as well + as list the trusted keys. Limiting which key(s) are able to sign which archive + is possible via the in &sources-list;. + + Note that a default installation already contains all keys to securily + acquire packages from the default repositories, so fiddling with + apt-key is only needed if third-party repositories are + added. + In order to add a new key you need to first download it (you should make sure you are using a trusted communication channel when retrieving it), add it with apt-key and @@ -171,10 +181,21 @@ gpg --clearsign -o InRelease Release and gpg -abs -o Release.gpg Release. - Publish the key fingerprint, - that way your users will know what key they need to import in - order to authenticate the files in the - archive. + + Publish the key fingerprint, that way your users + will know what key they need to import in order to authenticate the files + in the archive. It is best to ship your key in its own keyring package + like &keyring-distro; does with &keyring-package; to be able to + distribute updates and key transitions automatically later. + + + + Provide instructions on how to add your archive and key. + If your users can't acquire your key securily the chain of trust described above is broken. + How you can help users add your key depends on your archive and target audience ranging + from having your keyring package included in another archive users already have configured + (like the default repositories of their distribution) to leverage the web of trust. + @@ -192,7 +213,7 @@ For more background information you might want to review the Debian +url="https://www.debian.org/doc/manuals/securing-debian-howto/ch7">Debian Security Infrastructure chapter of the Securing Debian Manual (available also in the harden-doc package) and the