X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/f98233c1b1e93ef1bb595bfc6e59c74d9e05eb6a..bc7a59dded57338e9b5e523726b246dbdd4e0935:/doc/apt-secure.8.xml diff --git a/doc/apt-secure.8.xml b/doc/apt-secure.8.xml index 20f473f77..9b4b7378d 100644 --- a/doc/apt-secure.8.xml +++ b/doc/apt-secure.8.xml @@ -1,15 +1,21 @@ <?xml version="1.0" encoding="utf-8" standalone="no"?> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ - -<!ENTITY % aptent SYSTEM "apt.ent"> -%aptent; - +<!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> - &apt-docinfo; - + <refentryinfo> + &apt-author.jgunthorpe; + &apt-author.team; + &apt-email; + &apt-product; + <!-- The last update date --> + <date>2015-10-14T00:00:00Z</date> + </refentryinfo> + <refmeta> <refentrytitle>apt-secure</refentrytitle> <manvolnum>8</manvolnum> @@ -39,37 +45,43 @@ <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 - 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, <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. + </para> + + <para> + If an archive doesn't have a signed Release file or no Release file at all + current APT versions will raise a warning in <command>update</command> + operations and frontends like <command>apt-get</command> will require + explicit confirmation if an installation request includes a package from + such an unauthenticated archive. </para> <para> - 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. <command>apt-get</command> will currently only warn - for unsigned archives, future releases might force all sources - to be verified before downloading packages from them. + 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 + <option>Acquire::AllowInsecureRepositories</option> to <literal>false</literal>. </para> <para> - The package frontends &apt-get;, &aptitude; and &synaptic; support this new - authentication feature. + Note: All APT-based package management frontends 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 archives</title> + <refsect1><title>Trusted repositories</title> - <para> - The chain of trust from an apt archive to the end user is made up of - different steps. <command>apt-secure</command> is the last step in - this chain, trusting an archive does not mean that the packages - that you trust it do not contain malicious code but means that you - trust the archive maintainer. Its the archive maintainer - responsibility to ensure that the archive integrity is correct. + <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 @@ -79,31 +91,31 @@ devscripts packages respectively).</para> <para> - The chain of trust in Debian starts when a maintainer uploads a new - package or a new version of a package to the Debian archive. This - upload in order to become effective needs to be signed by a key of - a maintainer within the Debian maintainer's keyring (available in - the debian-keyring package). Maintainer's keys are signed by + 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 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. </para> <para> Once the uploaded package is verified and included in the archive, - the maintainer signature is stripped off, an MD5 sum of the package - is computed and put in the Packages file. The MD5 sum 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 (which is created - once a year and distributed through the FTP server. This key is - also on the Debian keyring. + 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> - Any end user can check the signature of the Release file, extract the MD5 - sum of a package from it and compare it with the MD5 sum of the - package he downloaded. Prior to version 0.6 only the MD5 sum of the - downloaded Debian package was checked. Now both the MD5 sum and the - signature of the Release file are checked. + 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 @@ -112,11 +124,11 @@ <itemizedlist> <listitem><para><literal>Network "man in the middle" - attacks</literal>. Without signature checking, a malicious - agent can introduce himself in the package download process and + 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 + rogue server (through ARP or DNS spoofing attacks).</para></listitem> <listitem><para><literal>Mirror network compromise</literal>. @@ -127,26 +139,29 @@ </itemizedlist> <para>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.</para> </refsect1> <refsect1><title>User configuration</title> <para> - <command>apt-key</command> 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 provide the - default Debian archive signing keys used in the Debian package - repositories. - </para> - <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 securily + 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>Release.gpg</filename> files from the archives you - have configured. + and verify the <filename>InRelease</filename> or <filename>Release.gpg</filename> + files from the archives you have configured. </para> </refsect1> @@ -157,36 +172,48 @@ </para> <itemizedlist> - <listitem><para><literal>Create a toplevel Release - file</literal>. if it does not exist already. You can do this + <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><literal>Sign it</literal>. You can do this by running + <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><literal>Publish the key fingerprint</literal>, - that way your users will know what key they need to import in - order to authenticate the files in the - archive.</para></listitem> + <listitem><para> + <emphasis>Publish the key fingerprint</emphasis>, 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. + </para></listitem> + + <listitem><para> + <emphasis>Provide instructions on how to add your archive and key</emphasis>. + 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. + </para></listitem> </itemizedlist> - <para>Whenever the contents of the archive changes (new packages + <para>Whenever the contents of the archive change (new packages are added or removed) the archive maintainer has to follow the - first two steps previously outlined.</para> + 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; +&debsign;, &debsig-verify;, &gpg; </para> <para>For more background information you might want to review the <ulink -url="http://www.debian.org/doc/manuals/securing-debian-howto/ch7.en.html">Debian +url="https://www.debian.org/doc/manuals/securing-debian-howto/ch7">Debian Security Infrastructure</ulink> chapter of the Securing Debian Manual (available also in the harden-doc package) and the <ulink url="http://www.cryptnet.net/fdp/crypto/strong_distro.html"