]> git.saurik.com Git - apt.git/blame - doc/apt-secure.8.xml
releasing version 0.9.7.9~exp3
[apt.git] / doc / apt-secure.8.xml
CommitLineData
d2793259 1<?xml version="1.0" encoding="utf-8" standalone="no"?>
81cf16a2
DK
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
d2793259
MV
4
5<!ENTITY % aptent SYSTEM "apt.ent">
6%aptent;
7
0c1a7101
DK
8<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent">
9%aptverbatiment;
10
d2793259
MV
11]>
12
13<refentry>
45fb8bf7
DK
14 <refentryinfo>
15 &apt-author.jgunthorpe;
16 &apt-author.team;
17 &apt-email;
18 &apt-product;
19 <!-- The last update date -->
dabb215c 20 <date>2012-06-09T00:00:00Z</date>
45fb8bf7
DK
21 </refentryinfo>
22
d2793259
MV
23 <refmeta>
24 <refentrytitle>apt-secure</refentrytitle>
25 <manvolnum>8</manvolnum>
f0599b9c 26 <refmiscinfo class="manual">APT</refmiscinfo>
d2793259
MV
27 </refmeta>
28
29<!-- NOTE: This manpage has been written based on the
30 Securing Debian Manual ("Debian Security
31 Infrastructure" chapter) and on documentation
32 available at the following sites:
33 http://wiki.debian.net/?apt06
34 http://www.syntaxpolice.org/apt-secure/
35 http://www.enyo.de/fw/software/apt-secure/
36-->
37<!-- TODO: write a more verbose example of how it works with
38 a sample similar to
39 http://www.debian-administration.org/articles/174
40 ?
41-->
42
43
44 <!-- Man page title -->
45 <refnamediv>
46 <refname>apt-secure</refname>
47 <refpurpose>Archive authentication support for APT</refpurpose>
48 </refnamediv>
49
50 <refsect1><title>Description</title>
51 <para>
52 Starting with version 0.6, <command>apt</command> contains code
53 that does signature checking of the Release file for all
54 archives. This ensures that packages in the archive can't be
55 modified by people who have no access to the Release file signing
56 key.
57 </para>
58
59 <para>
75d9bdba
JR
60 If a package comes from a archive without a signature, or with a
61 signature that apt does not have a key for, that package is
62 considered untrusted, and installing it will result in a big
d2793259 63 warning. <command>apt-get</command> will currently only warn
75d9bdba 64 for unsigned archives; future releases might force all sources
d2793259
MV
65 to be verified before downloading packages from them.
66 </para>
67
68 <para>
69 The package frontends &apt-get;, &aptitude; and &synaptic; support this new
70 authentication feature.
71 </para>
72</refsect1>
73
74 <refsect1><title>Trusted archives</title>
75
76 <para>
77 The chain of trust from an apt archive to the end user is made up of
75d9bdba
JR
78 several steps. <command>apt-secure</command> is the last step in
79 this chain; trusting an archive does not mean that you trust its
80 packages not to contain malicious code, but means that you
81 trust the archive maintainer. It's the archive maintainer's
82 responsibility to ensure that the archive's integrity is preserved.
d2793259
MV
83 </para>
84
85 <para>apt-secure does not review signatures at a
86 package level. If you require tools to do this you should look at
87 <command>debsig-verify</command> and
88 <command>debsign</command> (provided in the debsig-verify and
89 devscripts packages respectively).</para>
90
91 <para>
92 The chain of trust in Debian starts when a maintainer uploads a new
75d9bdba
JR
93 package or a new version of a package to the Debian archive. In
94 order to become effective, this upload needs to be signed by a key
95 contained in the Debian Maintainers keyring (available in
96 the debian-keyring package). Maintainers' keys are signed by
d2793259
MV
97 other maintainers following pre-established procedures to
98 ensure the identity of the key holder.
99 </para>
100
101 <para>
102 Once the uploaded package is verified and included in the archive,
75d9bdba
JR
103 the maintainer signature is stripped off, and checksums of the package
104 are computed and put in the Packages file. The checksums of all of the
105 Packages files are then computed and put into the Release file. The
dabb215c 106 Release file is then signed by the archive key for this Debian release,
75d9bdba
JR
107 and distributed alongside the packages and the Packages files on
108 Debian mirrors. The keys are in the Debian archive keyring available in
109 the <package>debian-archive-keyring</package> package.
d2793259
MV
110 </para>
111
112 <para>
75d9bdba
JR
113 End users can check the signature of the Release file, extract a checksum
114 of a package from it and compare it with the checksum of the package
115 they downloaded by hand - or rely on APT doing this automatically.
d2793259
MV
116 </para>
117
118 <para>Notice that this is distinct from checking signatures on a
119 per package basis. It is designed to prevent two possible attacks:
120 </para>
121
122 <itemizedlist>
123 <listitem><para><literal>Network "man in the middle"
75d9bdba
JR
124 attacks</literal>. Without signature checking, malicious
125 agents can introduce themselves into the package download process and
d2793259
MV
126 provide malicious software either by controlling a network
127 element (router, switch, etc.) or by redirecting traffic to a
75d9bdba 128 rogue server (through ARP or DNS spoofing
d2793259
MV
129 attacks).</para></listitem>
130
131 <listitem><para><literal>Mirror network compromise</literal>.
132 Without signature checking, a malicious agent can compromise a
6141cfe0 133 mirror host and modify the files in it to propagate malicious
d2793259
MV
134 software to all users downloading packages from that
135 host.</para></listitem>
136 </itemizedlist>
137
138 <para>However, it does not defend against a compromise of the
139 Debian master server itself (which signs the packages) or against a
140 compromise of the key used to sign the Release files. In any case,
141 this mechanism can complement a per-package signature.</para>
142</refsect1>
143
144 <refsect1><title>User configuration</title>
145 <para>
146 <command>apt-key</command> is the program that manages the list
75d9bdba
JR
147 of keys used by apt. It can be used to add or remove keys, although
148 an installation of this release will automatically contain the
d2793259
MV
149 default Debian archive signing keys used in the Debian package
150 repositories.
151 </para>
152 <para>
153 In order to add a new key you need to first download it
154 (you should make sure you are using a trusted communication channel
155 when retrieving it), add it with <command>apt-key</command> and
156 then run <command>apt-get update</command> so that apt can download
fe0f7911
DK
157 and verify the <filename>InRelease</filename> or <filename>Release.gpg</filename>
158 files from the archives you have configured.
d2793259
MV
159 </para>
160</refsect1>
161
162<refsect1><title>Archive configuration</title>
163 <para>
164 If you want to provide archive signatures in an archive under your
165 maintenance you have to:
166 </para>
167
168 <itemizedlist>
5f4331c4
DK
169 <listitem><para><emphasis>Create a toplevel Release
170 file</emphasis>, if it does not exist already. You can do this
d2793259 171 by running <command>apt-ftparchive release</command>
e3a1f08d 172 (provided in apt-utils).</para></listitem>
d2793259 173
5f4331c4 174 <listitem><para><emphasis>Sign it</emphasis>. You can do this by running
fe0f7911 175 <command>gpg --clearsign -o InRelease Release</command> and
d2793259
MV
176 <command>gpg -abs -o Release.gpg Release</command>.</para></listitem>
177
5f4331c4 178 <listitem><para><emphasis>Publish the key fingerprint</emphasis>,
d2793259
MV
179 that way your users will know what key they need to import in
180 order to authenticate the files in the
181 archive.</para></listitem>
182
183 </itemizedlist>
184
75d9bdba 185 <para>Whenever the contents of the archive change (new packages
d2793259 186 are added or removed) the archive maintainer has to follow the
75d9bdba 187 first two steps outlined above.</para>
d2793259
MV
188
189</refsect1>
190
191<refsect1><title>See Also</title>
192<para>
2f493cc6 193&apt-conf;, &apt-get;, &sources-list;, &apt-key;, &apt-ftparchive;,
d2793259
MV
194&debsign; &debsig-verify;, &gpg;
195</para>
196
e3a1f08d 197<para>For more background information you might want to review the
d2793259 198<ulink
96273866 199url="http://www.debian.org/doc/manuals/securing-debian-howto/ch7">Debian
d2793259
MV
200Security Infrastructure</ulink> chapter of the Securing Debian Manual
201(available also in the harden-doc package) and the
202<ulink url="http://www.cryptnet.net/fdp/crypto/strong_distro.html"
203>Strong Distribution HOWTO</ulink> by V. Alex Brennen. </para>
204
205</refsect1>
206
207 &manbugs;
208 &manauthor;
209
c3f389d0
MV
210<refsect1><title>Manpage Authors</title>
211
2ac470e1
MV
212<para>This man-page is based on the work of Javier Fernández-Sanguino
213Peña, Isaac Jones, Colin Walters, Florian Weimer and Michael Vogt.
c3f389d0
MV
214</para>
215
216</refsect1>
217
218
d2793259
MV
219</refentry>
220