diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/apt-key.8.xml | 47 | ||||
| -rw-r--r-- | doc/apt-secure.8.xml | 209 | ||||
| -rw-r--r-- | doc/apt.conf.5.xml | 2 | ||||
| -rw-r--r-- | doc/apt.ent | 49 | ||||
| -rw-r--r-- | doc/apt_preferences.5.xml | 2 | ||||
| -rw-r--r-- | doc/examples/apt-ftparchive.conf | 46 | ||||
| -rw-r--r-- | doc/makefile | 3 |
7 files changed, 351 insertions, 7 deletions
diff --git a/doc/apt-key.8.xml b/doc/apt-key.8.xml index 62686618a..eac61307d 100644 --- a/doc/apt-key.8.xml +++ b/doc/apt-key.8.xml @@ -68,17 +68,56 @@ <para> List trusted keys. + </para> </listitem> </varlistentry> + + <varlistentry><term>update</term> + <listitem> + <para> + + Update the local keyring with the keyring of Debian archive + keys and removes from the keyring the archive keys which are no + longer valid. + + </para> + + </listitem> + </varlistentry> + </variablelist> +</refsect1> + + <refsect1><title>Files</title> + <variablelist> + <varlistentry><term><filename>/etc/apt/trusted.gpg</filename></term> + <listitem><para>Keyring of local trusted keys, new keys will be added here.</para></listitem> + </varlistentry> + + <varlistentry><term><filename>/etc/apt/trustdb.gpg</filename></term> + <listitem><para>Local trust database of archive keys.</para></listitem> + </varlistentry> + + <varlistentry><term><filename>/usr/share/keyrings/debian-archive-keyring.gpg</filename></term> + <listitem><para>Keyring of Debian archive trusted keys.</para></listitem> + </varlistentry> + + <varlistentry><term><filename>/usr/share/keyrings/debian-archive-removed-keys.gpg</filename></term> + <listitem><para>Keyring of Debian archive removed trusted keys.</para></listitem> + </varlistentry> + + + </variablelist> + </refsect1> -<!-- <refsect1><title>See Also</title> --> -<!-- <para> --> -<!-- &apt-conf;, &apt-get;, &sources-list; --> -<!-- </refsect1> --> +<refsect1><title>See Also</title> +<para> +&apt-get;, &apt-secure; +</para> +</refsect1> &manbugs; &manauthor; 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/apt.conf.5.xml b/doc/apt.conf.5.xml index 69e212243..43f33681f 100644 --- a/doc/apt.conf.5.xml +++ b/doc/apt.conf.5.xml @@ -284,7 +284,7 @@ DPkg::Pre-Install-Pkgs {"/usr/sbin/dpkg-preconfigure --apt";}; <literal>sourcelist</literal> gives the location of the sourcelist and <literal>main</literal> is the default configuration file (setting has no effect, unless it is done from the config file specified by - <envar>APT_CONFIG</envar>.</para> + <envar>APT_CONFIG</envar>).</para> <para>The <literal>Dir::Parts</literal> setting reads in all the config fragments in lexical order from the directory specified. After this is done then the diff --git a/doc/apt.ent b/doc/apt.ent index 8054a25f6..cf22df6d2 100644 --- a/doc/apt.ent +++ b/doc/apt.ent @@ -44,6 +44,25 @@ </citerefentry>" > +<!ENTITY apt-key "<citerefentry> + <refentrytitle><command>apt-key</command></refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>" +> + +<!ENTITY apt-secure "<citerefentry> + <refentrytitle>apt-secure</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>" +> + +<!ENTITY apt-archive "<citerefentry> + <refentrytitle><filename>apt-archive</filename></refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>" +> + + <!ENTITY sources-list "<citerefentry> <refentrytitle><filename>sources.list</filename></refentrytitle> <manvolnum>5</manvolnum> @@ -91,6 +110,36 @@ <manvolnum>8</manvolnum> </citerefentry>" > + +<!ENTITY aptitude "<citerefentry> + <refentrytitle><command>aptitude</command></refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>" +> + +<!ENTITY synaptic "<citerefentry> + <refentrytitle><command>synaptic</command></refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>" +> + +<!ENTITY debsign "<citerefentry> + <refentrytitle><command>debsign</command></refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>" +> + +<!ENTITY debsig-verify "<citerefentry> + <refentrytitle><command>debsig-verify</command></refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>" +> + +<!ENTITY gpg "<citerefentry> + <refentrytitle><command>gpg</command></refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry>" +> <!-- Boiler plate docinfo section --> <!ENTITY apt-docinfo " diff --git a/doc/apt_preferences.5.xml b/doc/apt_preferences.5.xml index 3e50bef8c..12b03196a 100644 --- a/doc/apt_preferences.5.xml +++ b/doc/apt_preferences.5.xml @@ -183,7 +183,7 @@ belonging to any distribution whose Archive name is "<literal>unstable</literal> <programlisting> Package: * Pin: release a=unstable -Pin-Priority: 50 +Pin-Priority: 500 </programlisting> <simpara>The following record assigns a high priority to all package versions diff --git a/doc/examples/apt-ftparchive.conf b/doc/examples/apt-ftparchive.conf new file mode 100644 index 000000000..657ec5440 --- /dev/null +++ b/doc/examples/apt-ftparchive.conf @@ -0,0 +1,46 @@ +// This config is for use with the pool-structure for the packages, thus we +// don't use a Tree Section in here + +// The debian archive should be in the current working dir +Dir { + ArchiveDir "."; + CacheDir "."; +}; + +// Create Packages, Packages.gz and Packages.bz2, remove what you don't need +Default { + Packages::Compress ". gzip bzip2"; + Sources::Compress ". gzip bzip2"; + Contents::Compress ". gzip bzip2"; +}; + +// Includes the main section. You can structure the directory tree under +// ./pool/main any way you like, apt-ftparchive will take any deb (and +// source package) it can find. This creates a Packages a Sources and a +// Contents file for these in the main section of the sid release +BinDirectory "pool/main" { + Packages "dists/sid/main/binary-i386/Packages"; + SrcPackages "dists/sid/main/source/Sources"; + Contents "dists/sid/Contents-i386"; +} + +// This is the same for the contrib section +BinDirectory "pool/contrib" { + Packages "dists/sid/contrib/binary-i386/Packages"; + SrcPackages "dists/sid/contrib/source/Sources"; + Contents "dists/sid/Contents-i386"; +} + +// This is the same for the non-free section +BinDirectory "pool/non-free" { + Packages "dists/sid/non-free/binary-i386/Packages"; + SrcPackages "dists/sid/non-free/source/Sources"; + Contents "dists/sid/Contents-i386"; +}; + +// By default all Packages should have the extension ".deb" +Default { + Packages { + Extensions ".deb"; + }; +}; diff --git a/doc/makefile b/doc/makefile index f34b3f6e5..31ee061fb 100644 --- a/doc/makefile +++ b/doc/makefile @@ -14,7 +14,8 @@ include $(DEBIANDOC_H) # XML man pages SOURCE = apt-cache.8 apt-get.8 apt-cdrom.8 apt.conf.5 sources.list.5 \ apt-config.8 apt_preferences.5 \ - apt-sortpkgs.1 apt-ftparchive.1 apt-extracttemplates.1 apt-key.8 + apt-sortpkgs.1 apt-ftparchive.1 apt-extracttemplates.1 \ + apt-key.8 apt-secure.8 INCLUDES = apt.ent include $(XML_MANPAGE_H) |