Adding upstream version 2.2.4.upstream/2.2.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 272 insertions, 0 deletions

diff --git a/doc/apt-secure.8.xml b/doc/apt-secure.8.xml
new file mode 100644
index 0000000..e334df9
--- /dev/null
+++ b/doc/apt-secure.8.xml
@@ -0,0 +1,272 @@
+<?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. Since version 1.5 changes
+   in the information contained in the Release file about the repository need to be
+   confirmed before APT continues to apply updates from this repository.
+   </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>Unsigned Repositories</title>
+   <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>
+   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>
+</refsect1>
+
+ <refsect1><title>Signed 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>Information changes</title>
+   <para>
+   A Release file contains beside the checksums for the files in the repository
+   also general information about the repository like the origin, codename or
+   version number of the release.
+   </para><para>
+   This information is shown in various places so a repository owner should always
+   ensure correctness. Further more user configuration like &apt-preferences;
+   can depend and make use of this information. Since version 1.5 the user must
+   therefore explicitly confirm changes to signal that the user is sufficiently
+   prepared e.g. for the new major release of the distribution shipped in the
+   repository (as e.g. indicated by the codename).
+   </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>Repository 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>