]> git.saurik.com Git - apt.git/blame - doc/apt-secure.8.xml
apt-private: #ifdef HAVE_STRUCT_STATFS_F_TYPE, not #if
[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" [
5abbf5bb
DK
4<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
5<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
6<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
d2793259
MV
7]>
8
9<refentry>
45fb8bf7
DK
10 <refentryinfo>
11 &apt-author.jgunthorpe;
12 &apt-author.team;
13 &apt-email;
14 &apt-product;
15 <!-- The last update date -->
c69e8255 16 <date>2016-07-08T00:00:00Z</date>
45fb8bf7
DK
17 </refentryinfo>
18
d2793259
MV
19 <refmeta>
20 <refentrytitle>apt-secure</refentrytitle>
21 <manvolnum>8</manvolnum>
f0599b9c 22 <refmiscinfo class="manual">APT</refmiscinfo>
d2793259
MV
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>
002b1bc4
DK
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
952ee63b
DK
51 have no access to the Release file signing key. Starting with version 1.1
52 <command>APT</command> requires repositories to provide recent authentication
53 information for unimpeded usage of the repository.
d2793259
MV
54 </para>
55
56 <para>
0900a074 57 If an archive has an unsigned Release file or no Release file at all
952ee63b
DK
58 current APT versions will refuse to download data from them by default
59 in <command>update</command> operations and even if forced to download
60 front-ends like &apt-get; will require explicit confirmation if an
61 installation request includes a package from such an unauthenticated
62 archive.
d2793259
MV
63 </para>
64
65 <para>
952ee63b
DK
66 As a temporary exception &apt-get; (not &apt;!) raises warnings only if it
67 encounters unauthenticated archives to give a slightly longer grace period
68 on this backward compatibility effecting change. This exception will be removed
69 in future releases and you can opt-out of this grace period by setting the
70 configuration option <option>Binary::apt-get::Acquire::AllowInsecureRepositories</option>
71 to <literal>false</literal> or <option>--no-allow-insecure-repositories</option>
72 on the command line.
73 </para>
74
75 <para>
76 You can force all APT clients to raise only warnings by setting the
77 configuration option <option>Acquire::AllowInsecureRepositories</option> to
d03b947b
DK
78 <literal>true</literal>. Individual repositories can also be allowed to be insecure
79 via the &sources-list; option <literal>allow-insecure=yes</literal>.
80 Note that insecure repositories are strongly discouraged and all options
81 to force apt to continue supporting them will eventually be removed.
952ee63b
DK
82 Users also have the <option>Trusted</option> option available to disable
83 even the warnings, but be sure to understand the implications as detailed in
84 &sources-list;.
85 </para>
86
87 <para>
88 A repository which previously was authentication but would loose this state in
89 an <command>update</command> operation raises an error in all APT clients
90 irrespective of the option to allow or forbid usage of insecure repositories.
91 The error can be overcome by additionally setting
92 <option>Acquire::AllowDowngradeToInsecureRepositories</option>
d03b947b
DK
93 to <literal>true</literal> or for Individual repositories with the &sources-list;
94 option <literal>allow-downgrade-to-insecure=yes</literal>.
002b1bc4
DK
95 </para>
96
97 <para>
0900a074 98 Note: All APT-based package management front-ends like &apt-get;, &aptitude;
002b1bc4
DK
99 and &synaptic; support this authentication feature, so this manpage uses
100 <literal>APT</literal> to refer to them all for simplicity only.
d2793259
MV
101 </para>
102</refsect1>
103
0900a074 104 <refsect1><title>Trusted Repositories</title>
d2793259 105
002b1bc4
DK
106 <para>
107 The chain of trust from an APT archive to the end user is made up of
75d9bdba
JR
108 several steps. <command>apt-secure</command> is the last step in
109 this chain; trusting an archive does not mean that you trust its
110 packages not to contain malicious code, but means that you
111 trust the archive maintainer. It's the archive maintainer's
112 responsibility to ensure that the archive's integrity is preserved.
d2793259
MV
113 </para>
114
115 <para>apt-secure does not review signatures at a
116 package level. If you require tools to do this you should look at
117 <command>debsig-verify</command> and
118 <command>debsign</command> (provided in the debsig-verify and
119 devscripts packages respectively).</para>
120
121 <para>
0900a074 122 The chain of trust in Debian starts (e.g.) when a maintainer uploads a new
75d9bdba
JR
123 package or a new version of a package to the Debian archive. In
124 order to become effective, this upload needs to be signed by a key
0900a074 125 contained in one of the Debian package maintainer keyrings (available in
75d9bdba 126 the debian-keyring package). Maintainers' keys are signed by
d2793259 127 other maintainers following pre-established procedures to
002b1bc4
DK
128 ensure the identity of the key holder. Similar procedures exist in all
129 Debian-based distributions.
d2793259
MV
130 </para>
131
132 <para>
133 Once the uploaded package is verified and included in the archive,
75d9bdba
JR
134 the maintainer signature is stripped off, and checksums of the package
135 are computed and put in the Packages file. The checksums of all of the
136 Packages files are then computed and put into the Release file. The
694ef56e 137 Release file is then signed by the archive key for this &keyring-distro; release,
75d9bdba 138 and distributed alongside the packages and the Packages files on
694ef56e
DK
139 &keyring-distro; mirrors. The keys are in the &keyring-distro; archive keyring
140 available in the &keyring-package; package.
d2793259
MV
141 </para>
142
143 <para>
75d9bdba
JR
144 End users can check the signature of the Release file, extract a checksum
145 of a package from it and compare it with the checksum of the package
146 they downloaded by hand - or rely on APT doing this automatically.
d2793259
MV
147 </para>
148
149 <para>Notice that this is distinct from checking signatures on a
150 per package basis. It is designed to prevent two possible attacks:
151 </para>
152
153 <itemizedlist>
154 <listitem><para><literal>Network "man in the middle"
75d9bdba
JR
155 attacks</literal>. Without signature checking, malicious
156 agents can introduce themselves into the package download process and
d2793259
MV
157 provide malicious software either by controlling a network
158 element (router, switch, etc.) or by redirecting traffic to a
75d9bdba 159 rogue server (through ARP or DNS spoofing
d2793259
MV
160 attacks).</para></listitem>
161
162 <listitem><para><literal>Mirror network compromise</literal>.
163 Without signature checking, a malicious agent can compromise a
6141cfe0 164 mirror host and modify the files in it to propagate malicious
d2793259
MV
165 software to all users downloading packages from that
166 host.</para></listitem>
167 </itemizedlist>
168
169 <para>However, it does not defend against a compromise of the
002b1bc4 170 master server itself (which signs the packages) or against a
d2793259
MV
171 compromise of the key used to sign the Release files. In any case,
172 this mechanism can complement a per-package signature.</para>
173</refsect1>
174
0900a074 175 <refsect1><title>User Configuration</title>
d2793259 176 <para>
002b1bc4
DK
177 <command>apt-key</command> is the program that manages the list of keys used
178 by APT to trust repositories. It can be used to add or remove keys as well
179 as list the trusted keys. Limiting which key(s) are able to sign which archive
180 is possible via the <option>Signed-By</option> in &sources-list;.
181 </para><para>
d04e44ac 182 Note that a default installation already contains all keys to securely
002b1bc4
DK
183 acquire packages from the default repositories, so fiddling with
184 <command>apt-key</command> is only needed if third-party repositories are
185 added.
186 </para><para>
d2793259
MV
187 In order to add a new key you need to first download it
188 (you should make sure you are using a trusted communication channel
189 when retrieving it), add it with <command>apt-key</command> and
190 then run <command>apt-get update</command> so that apt can download
fe0f7911
DK
191 and verify the <filename>InRelease</filename> or <filename>Release.gpg</filename>
192 files from the archives you have configured.
d2793259
MV
193 </para>
194</refsect1>
195
0900a074 196<refsect1><title>Archive Configuration</title>
d2793259
MV
197 <para>
198 If you want to provide archive signatures in an archive under your
199 maintenance you have to:
200 </para>
201
202 <itemizedlist>
5f4331c4
DK
203 <listitem><para><emphasis>Create a toplevel Release
204 file</emphasis>, if it does not exist already. You can do this
d2793259 205 by running <command>apt-ftparchive release</command>
e3a1f08d 206 (provided in apt-utils).</para></listitem>
d2793259 207
5f4331c4 208 <listitem><para><emphasis>Sign it</emphasis>. You can do this by running
fe0f7911 209 <command>gpg --clearsign -o InRelease Release</command> and
d2793259
MV
210 <command>gpg -abs -o Release.gpg Release</command>.</para></listitem>
211
002b1bc4 212 <listitem><para>
0900a074 213 <emphasis>Publish the key fingerprint</emphasis>, so that your users
002b1bc4
DK
214 will know what key they need to import in order to authenticate the files
215 in the archive. It is best to ship your key in its own keyring package
216 like &keyring-distro; does with &keyring-package; to be able to
217 distribute updates and key transitions automatically later.
218 </para></listitem>
219
220 <listitem><para>
221 <emphasis>Provide instructions on how to add your archive and key</emphasis>.
d04e44ac 222 If your users can't acquire your key securely the chain of trust described above is broken.
002b1bc4
DK
223 How you can help users add your key depends on your archive and target audience ranging
224 from having your keyring package included in another archive users already have configured
0900a074 225 (like the default repositories of their distribution) to leveraging the web of trust.
002b1bc4 226 </para></listitem>
d2793259
MV
227
228 </itemizedlist>
229
75d9bdba 230 <para>Whenever the contents of the archive change (new packages
d2793259 231 are added or removed) the archive maintainer has to follow the
75d9bdba 232 first two steps outlined above.</para>
d2793259
MV
233
234</refsect1>
235
236<refsect1><title>See Also</title>
237<para>
2f493cc6 238&apt-conf;, &apt-get;, &sources-list;, &apt-key;, &apt-ftparchive;,
480c2414 239&debsign;, &debsig-verify;, &gpg;
d2793259
MV
240</para>
241
e3a1f08d 242<para>For more background information you might want to review the
d2793259 243<ulink
002b1bc4 244url="https://www.debian.org/doc/manuals/securing-debian-howto/ch7">Debian
d2793259 245Security Infrastructure</ulink> chapter of the Securing Debian Manual
0900a074 246(also available in the harden-doc package) and the
d2793259
MV
247<ulink url="http://www.cryptnet.net/fdp/crypto/strong_distro.html"
248>Strong Distribution HOWTO</ulink> by V. Alex Brennen. </para>
249
250</refsect1>
251
252 &manbugs;
253 &manauthor;
254
c3f389d0
MV
255<refsect1><title>Manpage Authors</title>
256
2ac470e1
MV
257<para>This man-page is based on the work of Javier Fernández-Sanguino
258Peña, Isaac Jones, Colin Walters, Florian Weimer and Michael Vogt.
c3f389d0
MV
259</para>
260
261</refsect1>
262
263
d2793259 264</refentry>