X-Git-Url: https://git.saurik.com/apt.git/blobdiff_plain/73e0ee1e7f97571d7be3277e3c25c2f41b2bb946..d27daedb6a0bf672508072100f20233d08ccf0e0:/doc/apt-secure.8.xml

diff --git a/doc/apt-secure.8.xml b/doc/apt-secure.8.xml
index 9696e018d..1cf6539c6 100644
--- a/doc/apt-secure.8.xml
+++ b/doc/apt-secure.8.xml
@@ -1,18 +1,25 @@
 <?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-15T00: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
@@ -38,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 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.
+   If an archive has an unsigned Release file or no Release file at all
+   current APT versions will raise a warning in <command>update</command>
+   operations and front-ends like <command>apt-get</command> will require
+   explicit confirmation if an installation request includes a package from
+   such an unauthenticated archive.
    </para>
 
    <para>
-   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
+   <option>Acquire::AllowInsecureRepositories</option> to <literal>false</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 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
@@ -78,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 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.
+   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
@@ -111,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>.
@@ -126,68 +139,83 @@
     </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>
+ <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>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>
 
-<refsect1><title>Archive configuration</title>
+<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><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>, 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 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
+(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>
 
@@ -206,4 +234,3 @@ Peña, Isaac Jones, Colin Walters, Florian Weimer and Michael Vogt.
  
 
 </refentry>
-