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