summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorChristian Perrier <bubulle@debian.org>2005-09-22 20:54:03 +0000
committerChristian Perrier <bubulle@debian.org>2005-09-22 20:54:03 +0000
commit741c12586fac0a9a5ed6ebc475479fee43e911a1 (patch)
treeae5bb663f318d9a0bbb652fdaee534fc05e9a764 /doc
parent5d90633977ce28194b83ac8c2787b2a9676855a0 (diff)
parent14cd494a9fa0d6801410bf121beb74ea631d59a6 (diff)
Merge with Michael Vogt's archive
Patches applied: * michael.vogt@ubuntu.com--2005/apt--bts225947--0--base-0 tag of apt@packages.debian.org/apt--main--0--patch-79 * michael.vogt@ubuntu.com--2005/apt--bts225947--0--patch-1 * merged with mainline and apt--fixes--0 * michael.vogt@ubuntu.com--2005/apt--bts225947--0--patch-2 * patch from aj (slighly modified to use auto_ptr<>) applied * michael.vogt@ubuntu.com--2005/apt--bts225947--0--patch-3 * changelog updated * michael.vogt@ubuntu.com--2005/apt--bts225947--0--patch-4 * work for arch=all packages too now * michael.vogt@ubuntu.com--2005/apt--bts225947--0--patch-5 * merged with apt--main--0 * michael.vogt@ubuntu.com--2005/apt--bts225947--0--patch-6 * fixed a incorrect po/he.po merge * michael.vogt@ubuntu.com--2005/apt--cdrom-fallback--0--base-0 tag of apt@packages.debian.org/apt--main--0--patch-110 * michael.vogt@ubuntu.com--2005/apt--cdrom-fallback--0--patch-1 * initial patch to make falling back from cdrom possible * michael.vogt@ubuntu.com--2005/apt--cdrom-fallback--0--patch-2 * fix in methods/cdrom.cc: don't call Fail() but return false so that apt can fallback to a differencent source * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-7 * fixed incorrect man-page example * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-8 * changelog udpate * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-9 * we only need to check once for xmlto * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-10 * fix a bug in a man-page, fix a problem with overly long lines in apt-cdrom * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-11 * merged with apt--main--0 * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-12 * fix a incorrect error message (it always added .gz regardless what was downloaded) * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-13 * merged with main * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-14 * added Hashsum support for file and cdrom * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-15 * added README.arch * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-16 * merged with main * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-17 * move the changelog to the right place * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-18 * Change pkgPolicy::Pin from private to protected * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-19 * added a default constructor for PrvIterator * michael.vogt@ubuntu.com--2005/apt--fixes--0--patch-20 * applied otavios patch to reread the statusFile on debSystem::Initialize * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-33 * merged with matt's tree * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-34 * merged with matts tree * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-35 * build debian and ubuntu package from the same source * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-36 * added debian/patches dir * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-37 * fix the breakage from my last commit (note to self: always, _always_ run baz diff before a commit) * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-38 * removed the lsb_release build patch (nobody except me seems to like it) * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-39 * merged from main * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-40 * merged the apt--sane-handle-timeout--0 branch * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-41 * merged apt--bts225947--0 * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-42 * merged with apt--main * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-43 * added patch that adds a apt-secure man-page (thanks to jfs@computer.org) * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-44 * added author credits * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-45 * added apt-ftparchive.conf example * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-46 * corrected the utf8 of javier fernandes pena * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-47 * improve the timeout handling (again) * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-48 * merged with apt--fixes--0 * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-49 * README.arch updates, comment in apt-pkg/algorithm.h added, apt-pkg/cacheiterators.h order in initlist changed to remove warning * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-50 * meda-change message is send over status-fd now * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-51 * include a human readable string for the MediaChange status-fd message as well * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-52 * finalizing changelog * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-53 * check ctime as well in cron.daily when cleaning up packages in apt.cron.daily * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-54 * fix a stupid typo in apt.cron.daily * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-55 * fix apt-pkg/cdrom.cc to umount the cdrom again if anything fails * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-56 * merged from apt--cdrom-fallback--0 * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-57 * changelog update * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-58 * better error string for a failed dpkg-source * michael.vogt@ubuntu.com--2005/apt--mvo--0--patch-59 * make sure that the pkgRecords D'tor does not segfault * michael.vogt@ubuntu.com--2005/apt--sane-handle-timeout--0--base-0 tag of apt@packages.debian.org/apt--main--0--patch-87 * michael.vogt@ubuntu.com--2005/apt--sane-handle-timeout--0--patch-1 * report timeouts (from Connect) and fail if they happen in pkgAcqMetaSig * michael.vogt@ubuntu.com--2005/apt--sane-handle-timeout--0--patch-2 * merged with the fixes branch to make it build again * michael.vogt@ubuntu.com--2005/apt--sane-handle-timeout--0--patch-3 * merged with main * otavio@debian.org--2005/apt--fixes--0--patch-28 Reread status configuration, needed for clients using independent apt ...
Diffstat (limited to 'doc')
-rw-r--r--doc/apt-key.8.xml47
-rw-r--r--doc/apt-secure.8.xml209
-rw-r--r--doc/apt.conf.5.xml2
-rw-r--r--doc/apt.ent49
-rw-r--r--doc/apt_preferences.5.xml2
-rw-r--r--doc/examples/apt-ftparchive.conf46
-rw-r--r--doc/makefile3
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)