diff options
Diffstat (limited to 'doc/apt-secure.8.xml')
| -rw-r--r-- | doc/apt-secure.8.xml | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/doc/apt-secure.8.xml b/doc/apt-secure.8.xml new file mode 100644 index 000000000..f1f63dae1 --- /dev/null +++ b/doc/apt-secure.8.xml @@ -0,0 +1,264 @@ +<?xml version="1.0" encoding="utf-8" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % aptent SYSTEM "apt.ent"> %aptent; +<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment; +<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor; +]> + +<refentry> + <refentryinfo> + &apt-author.jgunthorpe; + &apt-author.team; + &apt-email; + &apt-product; + <!-- The last update date --> + <date>2016-08-06T00:00:00Z</date> + </refentryinfo> + + <refmeta> + <refentrytitle>apt-secure</refentrytitle> + <manvolnum>8</manvolnum> + <refmiscinfo class="manual">APT</refmiscinfo> + </refmeta> + +<!-- NOTE: This manpage has been written based on the + Securing Debian Manual ("Debian Security + Infrastructure" chapter) and on documentation + available at the following sites: + http://wiki.debian.net/?apt06 + http://www.syntaxpolice.org/apt-secure/ + http://www.enyo.de/fw/software/apt-secure/ +--> +<!-- TODO: write a more verbose example of how it works with + a sample similar to + http://www.debian-administration.org/articles/174 + ? +--> + + + <!-- Man page title --> + <refnamediv> + <refname>apt-secure</refname> + <refpurpose>Archive authentication support for APT</refpurpose> + </refnamediv> + + <refsect1><title>Description</title> + <para> + Starting with version 0.6, <command>APT</command> 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. Starting with version 1.1 + <command>APT</command> requires repositories to provide recent authentication + information for unimpeded usage of the repository. + </para> + + <para> + If an archive has an unsigned Release file or no Release file at all + current APT versions will refuse to download data from them by default + in <command>update</command> operations and even if forced to download + front-ends like &apt-get; will require explicit confirmation if an + installation request includes a package from such an unauthenticated + archive. + </para> + + <para> + As a temporary exception &apt-get; (not &apt;!) raises warnings only if it + encounters unauthenticated archives to give a slightly longer grace period + on this backward compatibility effecting change. This exception will be removed + in future releases and you can opt-out of this grace period by setting the + configuration option <option>Binary::apt-get::Acquire::AllowInsecureRepositories</option> + to <literal>false</literal> or <option>--no-allow-insecure-repositories</option> + on the command line. + </para> + + <para> + You can force all APT clients to raise only warnings by setting the + configuration option <option>Acquire::AllowInsecureRepositories</option> to + <literal>true</literal>. Individual repositories can also be allowed to be insecure + via the &sources-list; option <literal>allow-insecure=yes</literal>. + Note that insecure repositories are strongly discouraged and all options + to force apt to continue supporting them will eventually be removed. + Users also have the <option>Trusted</option> option available to disable + even the warnings, but be sure to understand the implications as detailed in + &sources-list;. + </para> + + <para> + A repository which previously was authenticated but would loose this state in + an <command>update</command> operation raises an error in all APT clients + irrespective of the option to allow or forbid usage of insecure repositories. + The error can be overcome by additionally setting + <option>Acquire::AllowDowngradeToInsecureRepositories</option> + to <literal>true</literal> or for Individual repositories with the &sources-list; + option <literal>allow-downgrade-to-insecure=yes</literal>. + </para> + + <para> + Note: All APT-based package management front-ends like &apt-get;, &aptitude; + and &synaptic; support this authentication feature, so this manpage uses + <literal>APT</literal> to refer to them all for simplicity only. + </para> +</refsect1> + + <refsect1><title>Trusted Repositories</title> + + <para> + The chain of trust from an APT archive to the end user is made up of + several steps. <command>apt-secure</command> 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 + trust the archive maintainer. It's the archive maintainer's + responsibility to ensure that the archive's integrity is preserved. + </para> + + <para>apt-secure does not review signatures at a + package level. If you require tools to do this you should look at + <command>debsig-verify</command> and + <command>debsign</command> (provided in the debsig-verify and + devscripts packages respectively).</para> + + <para> + The chain of trust in Debian starts (e.g.) 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 one of the Debian package maintainer 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. Similar procedures exist in all + Debian-based distributions. + </para> + + <para> + Once the uploaded package is verified and included in the archive, + the maintainer signature is stripped off, and checksums of the package + are computed and put in the Packages file. The checksums of all of the + Packages files are then computed and put into the Release file. The + Release file is then signed by the archive key for this &keyring-distro; release, + and distributed alongside the packages and the Packages files on + &keyring-distro; mirrors. The keys are in the &keyring-distro; archive keyring + available in the &keyring-package; package. + </para> + + <para> + End users can check the signature of the Release file, extract a checksum + of a package from it and compare it with the checksum of the package + they downloaded by hand - or rely on APT doing this automatically. + </para> + + <para>Notice that this is distinct from checking signatures on a + per package basis. It is designed to prevent two possible attacks: + </para> + + <itemizedlist> + <listitem><para><literal>Network "man in the middle" + attacks</literal>. Without signature checking, malicious + agents can introduce themselves into the package download process and + provide malicious software either by controlling a network + element (router, switch, etc.) or by redirecting traffic to a + rogue server (through ARP or DNS spoofing + attacks).</para></listitem> + + <listitem><para><literal>Mirror network compromise</literal>. + Without signature checking, a malicious agent can compromise a + mirror host and modify the files in it to propagate malicious + software to all users downloading packages from that + host.</para></listitem> + </itemizedlist> + + <para>However, it does not defend against a compromise of the + 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.</para> +</refsect1> + + <refsect1><title>User Configuration</title> + <para> + <command>apt-key</command> 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 <option>Signed-By</option> in &sources-list;. + </para><para> + Note that a default installation already contains all keys to securely + acquire packages from the default repositories, so fiddling with + <command>apt-key</command> is only needed if third-party repositories are + added. + </para><para> + 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 <command>apt-key</command> and + then run <command>apt-get update</command> so that apt can download + and verify the <filename>InRelease</filename> or <filename>Release.gpg</filename> + files from the archives you have configured. + </para> +</refsect1> + +<refsect1><title>Archive Configuration</title> + <para> + If you want to provide archive signatures in an archive under your + maintenance you have to: + </para> + + <itemizedlist> + <listitem><para><emphasis>Create a toplevel Release + file</emphasis>, if it does not exist already. You can do this + by running <command>apt-ftparchive release</command> + (provided in apt-utils).</para></listitem> + + <listitem><para><emphasis>Sign it</emphasis>. You can do this by running + <command>gpg --clearsign -o InRelease Release</command> and + <command>gpg -abs -o Release.gpg Release</command>.</para></listitem> + + <listitem><para> + <emphasis>Publish the key fingerprint</emphasis>, so that 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. + </para></listitem> + + <listitem><para> + <emphasis>Provide instructions on how to add your archive and key</emphasis>. + If your users can't acquire your key securely 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 leveraging the web of trust. + </para></listitem> + + </itemizedlist> + + <para>Whenever the contents of the archive change (new packages + are added or removed) the archive maintainer has to follow the + first two steps outlined above.</para> + +</refsect1> + +<refsect1><title>See Also</title> +<para> +&apt-conf;, &apt-get;, &sources-list;, &apt-key;, &apt-ftparchive;, +&debsign;, &debsig-verify;, &gpg; +</para> + +<para>For more background information you might want to review the +<ulink +url="https://www.debian.org/doc/manuals/securing-debian-howto/ch7">Debian +Security Infrastructure</ulink> chapter of the Securing Debian Manual +(also available in the harden-doc package) and the +<ulink url="http://www.cryptnet.net/fdp/crypto/strong_distro.html" +>Strong Distribution HOWTO</ulink> by V. Alex Brennen. </para> + +</refsect1> + + &manbugs; + &manauthor; + +<refsect1><title>Manpage Authors</title> + +<para>This man-page is based on the work of Javier Fernández-Sanguino +Peña, Isaac Jones, Colin Walters, Florian Weimer and Michael Vogt. +</para> + +</refsect1> + + +</refentry> |