* added the apt-secure manpage

2 files changed, 426 insertions, 0 deletions

diff --git a/doc/apt-secure.8.xml b/doc/apt-secure.8.xml
new file mode 100644
index 000000000..e22446030
--- /dev/null
+++ b/doc/apt-secure.8.xml
@@ -0,0 +1,209 @@
+<?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;
+
+]>
+
+<refentry>
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-secure</refentrytitle>
+   <manvolnum>8</manvolnum>
+ </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
+   archives. This ensures that 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.
+   </para>
+
+   <para>
+   The package frontends &apt-get;, &aptitude; and &synaptic; support this new
+   authentication feature.
+   </para>
+</refsect1>
+
+ <refsect1><title>Trusted archives</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>
+
+   <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 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
+   other maintainers following pre-established procedures to
+   ensure the identity of the key holder.
+   </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.
+   </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.
+   </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, a malicious
+       agent can introduce himself in 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 propage malicious
+        software to all users downloading packages from that
+        host.</para></listitem>
+    </itemizedlist>
+
+   <para>However, it does not defend against a compromise of the
+   Debian 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>
+   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.
+   </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><literal>Create a toplevel Release
+       file</literal>.  if it does not exist already. You can do this
+       by running <command>apt-ftparchive release</command> 
+       (provided inftp apt-utils).</para></listitem>
+   
+      <listitem><para><literal>Sign it</literal>. You can do this by running
+      <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>
+
+    </itemizedlist>
+
+    <para>Whenever the contents of the archive changes (new packages
+    are added or removed) the archive maintainer has to follow the
+    first two steps previously outlined.</para>
+
+</refsect1>
+
+<refsect1><title>See Also</title> 
+<para> 
+&apt-conf;, &apt-get;, &sources-list;, &apt-key;, &apt-archive;,
+&debsign; &debsig-verify;, &gpg;
+</para>
+
+<para>For more backgound information you might want to review the
+<ulink
+url="http://www.debian.org/doc/manuals/securing-debian-howto/ch7.en.html">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"
+>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>
+
diff --git a/doc/fr/apt-secure.fr.8.xml b/doc/fr/apt-secure.fr.8.xml
new file mode 100644
index 000000000..5cec9a49d
--- /dev/null
+++ b/doc/fr/apt-secure.fr.8.xml
@@ -0,0 +1,217 @@
+<?xml version="1.0" encoding="iso-8859-15" 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.fr">
+%aptent;
+
+]>
+
+<refentry lang="fr">
+ &apt-docinfo;
+ 
+ <refmeta>
+   <refentrytitle>apt-secure</refentrytitle>
+   <manvolnum>8</manvolnum>
+ </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>Certification d'archive avec APT</refpurpose>
+ </refnamediv>
+
+ <refsect1><title>Description</title>
+   <para>
+   Depuis sa version 0.6, <command>apt</command> sait vérifier 
+la signature du fichier Release de chaque archive. On s'assure ainsi que les
+paquets de cette archive ne peuvent pas être modifiés par quelqu'un qui ne 
+possède pas la clé de la signature du fichier Release.
+   </para>
+
+   <para>
+   Quand un paquet provient d'une archive sans signature ou d'une archive avec 
+une signature dont apt ne possède pas la clé, ce paquet n'est pas considéré 
+comme fiable et son installation provoquera un avertissement. Pour 
+l'instant, <command>apt-get</command> ne signale que les archives sans 
+signature&nbsp;; les prochaines versions pourraient rendre obligatoire la 
+vérification des sources avant tout téléchargement de paquet.
+   </para>
+
+   <para>
+   Les paquets &apt-get;, &aptitude; et &synaptic; possèdent cette nouvelle 
+fonction de certification. 
+
+   </para>
+</refsect1>
+
+ <refsect1><title>Archives fiables</title> 
+
+   <para> 
+   D'une archive apt jusqu'à l'utilisateur, la confiance se construit en 
+plusieurs étapes. <command>Apt-secure</command> est la dernière étape. Faire 
+confiance à une archive ne signifie pas que les paquets qu'elle contient 
+sont exempts de code malveillant, mais signifie que vous faites confiance au 
+responsable de l'archive. C'est ensuite au responsable de l'archive de faire 
+en sorte que l'archive soit fiable. 
+
+   </para>
+
+   <para><command>Apt-secure</command> n'examine pas la signature d'un 
+paquet. Certains programmes peuvent le faire comme 
+<command>debsig-verify</command> ou <command>debsign</command>, qu'on peut 
+trouver dans les paquets debsig-verify et devscripts.
+</para>
+
+   <para>
+   La fiabilisation dans Debian commence quand un responsable de paquet envoie 
+un nouveau paquet ou une nouvelle version d'un paquet dans l'archive. Cet 
+envoi, pour être effectif, doit être signé avec la clé d'un responsable qui 
+se trouve dans le trousseau des responsables Debian (disponible dans le 
+paquet debian-keyring). Les clés des responsables de paquet sont signées par 
+d'autres responsables, suivant des procédures préétablies pour s'assurer de 
+l'identité des propriétaires de la clé.
+
+   </para>
+
+   <para>
+   Une fois le paquet vérifié et archivé, la signature du responsable est 
+enlevée, une somme MD5 du paquet est calculée et mise dans le fichier 
+Packages. Une somme MD5 de tous les paquets est ensuite calculée et mise 
+dans le fichier Release. Ce fichier est signé par la clé de l'archive. Cette 
+clé qui est créée chaque année et distribuée par le serveur FTP se trouve 
+aussi dans le trousseau Debian.
+
+   </para>
+
+   <para>
+   Un utilisateur peut consulter la signature du fichier Release, extraire la 
+somme MD5 d'un paquet et la comparer avec la somme du paquet qu'il a 
+téléchargé. Avant la version 0.6, seule la somme du paquet téléchargé était 
+vérifiée. Maintenant on peut vérifier aussi la signature du fichier Release.
+
+   </para>
+
+   <para>Cette façon de faire est différente d'une vérification de la signature d'un 
+paquet. Elle vise à empêcher deux types d'attaque possibles&nbsp;: 
+
+   </para>
+
+    <itemizedlist>
+       <listitem><para>
+L'attaque de type <quote>homme au milieu</quote>. Sans vérification de 
+signature, quelqu'un de malveillant peut s'introduire au milieu du 
+processus de téléchargement et insérer du code soit en contrôlant un élément 
+du réseau, routeur, commutateur, etc. soit en détournant le trafic vers un 
+serveur fourbe (par usurpation d'adresses).
+</para></listitem>
+ 
+       <listitem><para>
+L'attaque par compromission d'un miroir sur le réseau.  Sans vérification de 
+signature, quelqu'un de malveillant peut compromettre un miroir et modifier 
+les fichiers. Ainsi tous ceux qui téléchargent les paquets de ce miroir 
+propagent du code malveillant.
+</para></listitem>
+    </itemizedlist>
+
+   <para>
+Cependant cette méthode ne garantit pas contre une compromission du serveur 
+Debian lui-même (qui signe les paquets) ni contre la compromission de la clé 
+qui sert à signer les fichiers Release. Mais elle peut compléter la 
+signature des paquets.
+</para>
+</refsect1>
+
+ <refsect1><title>Configuration</title>
+   <para>
+   Le programme qui gère la liste des clés utilisées par apt s'appelle 
+<command>apt-key</command>. Il peut ajouter ou supprimer des clés. Cette 
+version installe automatiquement les clés qui servent à signer l'archive 
+Debian et les différents répertoires de paquets. 
+
+   </para>
+   <para>
+   Pour ajouter une clé, vous devez d'abord la télécharger. Il vaut mieux 
+utiliser un canal fiable pour ce téléchargement. Ensuite vous l'ajoutez avec 
+la commande <command>apt-key</command> et vous lancez la commande 
+<command>apt-get update</command> pour télécharger et vérifier le fichier 
+<filename>Release.gpg</filename> de l'archive que vous avez configurée.
+
+   </para>
+</refsect1>
+
+<refsect1><title>Configuration d'une archive</title>
+   <para>
+   Si vous voulez signer les archives dont vous avez la responsabilité, vous 
+devez&nbsp;:
+
+   </para>
+
+     <itemizedlist>
+       <listitem><para>créer un fichier Release à la racine de l'archive, s'il n'existe pas 
+déjà. Vous pouvez le créer avec la commande <command>apt-ftparchive release</command> 
+(fournie dans le paquet apt-utils)&nbsp;;
+</para></listitem>
+   
+      <listitem><para>
+le signer, avec la commande <command>gpg -abs -o Release.gpg Release</command>&nbsp;;
+</para></listitem>
+
+      <listitem><para>
+publier l'empreinte de la clé. Ainsi les utilisateurs de votre archive 
+connaîtront la clé qu'ils doivent importer pour authentifier les fichiers de 
+l'archive.
+</para></listitem>
+
+    </itemizedlist>
+
+    <para>Chaque fois que le contenu de l'archive change, le responsable doit refaire 
+les deux premières étapes.
+</para>
+
+</refsect1>
+
+<refsect1><title>Voir aussi</title> 
+<para> 
+&apt-conf;, &apt-get;,&sources-list;, &apt-key;, &apt-archive;, &debsign;, 
+&debsig-verify;, &gpg;
+
+</para>
+
+<para>Pour des informations plus substantielles, vous pouvez consulter 
+<ulink url="http://www.debian.org/doc/manuals/securing-debian-howto/ch7.en.html">
+l'infrastructure debian pour la sécurité</ulink> un chapitre du manuel Debian sur la sécurité 
+(disponible dans le paquet harden-doc) et le 
+<ulink url="http://www.cryptnet.net/fdp/crypto/strong_distro.html">Strong Distribution HOWTO</ulink> par V. Alex Brennen.
+  </para>
+
+</refsect1>
+
+ &manbugs;
+ &manauthor;
+
+<refsect1><title>Auteurs</title> 
+
+<para>
+Cette page a été écrite à partir des travaux de Javier Fernández-Sanguino Peña, Isaac 
+Jones, Colin Walters, Florian Weimer et Michael Vogt.
+</para>
+  </refsect1>
+&traducteur;
+ 
+</refentry>