report progress for triggered actions

[apt.git] / doc / apt-secure.8.xml

diff --git a/doc/apt-secure.8.xml b/doc/apt-secure.8.xml
index 981351615fde69672fcbef7bdd7c164a89961ace..75c4dc61e3934d0303fff5b3adcd6b17a3956cef 100644 (file)
--- a/doc/apt-secure.8.xml
+++ b/doc/apt-secure.8.xml
@@ -1,15 +1,9 @@
 <?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" [
 <?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;
+<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
+<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
+<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;

 ]>
 
 <refentry>
 ]>
 
 <refentry>


@@ -19,7 +13,7 @@
    &apt-email;
    &apt-product;
    <!-- The last update date -->
    &apt-email;
    &apt-product;
    <!-- The last update date -->

-   <date>2012-06-09T00:00:00Z</date>
+   <date>2016-07-07T00:00:00Z</date>

  </refentryinfo>
 
  <refmeta>
  </refentryinfo>
 
  <refmeta>


@@ -51,32 +45,66 @@
 
  <refsect1><title>Description</title>
    <para>
 
  <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. 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>
    </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.
+   A repository which previously was authentication 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>
    </para>
 
    <para>

-   The package frontends &apt-get;, &aptitude; and &synaptic; support this new
-   authentication feature.
+   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>
 
    </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
+   <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
    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


@@ -91,13 +119,14 @@
    devscripts packages respectively).</para>
 
    <para>
    devscripts packages respectively).</para>
 
    <para>

-   The chain of trust in Debian starts when a maintainer uploads a new
+   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
    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 maintainer keyrings (available in

    the debian-keyring package). Maintainers' keys are signed by
    other maintainers following pre-established procedures to
    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>
    </para>
 
    <para>


@@ -138,20 +167,23 @@
     </itemizedlist>
 
    <para>However, it does not defend against a compromise of the
     </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>
 
    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 contain the
-   default Debian archive signing keys used in the Debian package
-   repositories.
-   </para>
+ <refsect1><title>User Configuration</title>

    <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 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
    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


@@ -161,7 +193,7 @@
    </para>
 </refsect1>
 
    </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>
    If you want to provide archive signatures in an archive under your
    maintenance you have to:


@@ -177,10 +209,21 @@
       <command>gpg --clearsign -o InRelease Release</command> and
       <command>gpg -abs -o Release.gpg Release</command>.</para></listitem>
 
       <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>,
-      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>
 
 
     </itemizedlist>
 


@@ -193,14 +236,14 @@
 <refsect1><title>See Also</title> 
 <para> 
 &apt-conf;, &apt-get;, &sources-list;, &apt-key;, &apt-ftparchive;,
 <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
 </para>
 
 <para>For more background information you might want to review the
 <ulink

-url="http://www.debian.org/doc/manuals/securing-debian-howto/ch7">Debian
+url="https://www.debian.org/doc/manuals/securing-debian-howto/ch7">Debian

 Security Infrastructure</ulink> chapter of the Securing Debian Manual
 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>
 
 <ulink url="http://www.cryptnet.net/fdp/crypto/strong_distro.html"
 >Strong Distribution HOWTO</ulink> by V. Alex Brennen.  </para>
 


@@ -219,4 +262,3 @@ Peña, Isaac Jones, Colin Walters, Florian Weimer and Michael Vogt.
  
 
 </refentry>
  
 
 </refentry>

-