286 lines
12 KiB
XML
286 lines
12 KiB
XML
<?xml version="1.0" encoding="utf-8" standalone="no"?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
|
|
<!ENTITY % aptent SYSTEM "apt.ent"> %aptent;
|
|
<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent"> %aptverbatiment;
|
|
<!ENTITY % aptvendor SYSTEM "apt-vendor.ent"> %aptvendor;
|
|
]>
|
|
|
|
<refentry>
|
|
<refentryinfo>
|
|
&apt-author.jgunthorpe;
|
|
&apt-author.team;
|
|
&apt-email;
|
|
&apt-product;
|
|
<!-- The last update date -->
|
|
<date>2024-11-23T00:00:00Z</date>
|
|
</refentryinfo>
|
|
|
|
<refmeta>
|
|
<refentrytitle>apt-secure</refentrytitle>
|
|
<manvolnum>8</manvolnum>
|
|
<refmiscinfo class="manual">APT</refmiscinfo>
|
|
</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 repositories. This ensures
|
|
that data like packages in the archive can't be modified by people who
|
|
have no access to the Release file signing key. Starting with version 1.1
|
|
<command>APT</command> requires repositories to provide recent authentication
|
|
information for unimpeded usage of the repository. Since version 1.5 changes
|
|
in the information contained in the Release file about the repository need to be
|
|
confirmed before APT continues to apply updates from this repository.
|
|
</para>
|
|
|
|
<para>
|
|
Note: All APT-based package management front-ends like &apt-get;, &aptitude;
|
|
and &synaptic; support this authentication feature, so this manpage uses
|
|
<literal>APT</literal> to refer to them all for simplicity only.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1><title>User Configuration</title>
|
|
<para>
|
|
Keys should usually be included inside their corresponding <literal>.sources</literal>
|
|
by embedding the ASCII-armored key in the <literal>Signed-By</literal> option.
|
|
To do so, replace the empty line with a dot, and then indent all lines by two spaces.
|
|
See &sources-list; for more information.
|
|
</para>
|
|
|
|
<para>
|
|
Alternatively, keys may be placed in <filename>/etc/apt/keyrings</filename> for local keys,
|
|
or <filename>/usr/share/keyrings</filename> for keys managed by packages, and then referenced
|
|
by <literal>Signed-By: /etc/apt/keyrings/example-archive-keyring.asc</literal> option in a <literal>.sources</literal>
|
|
file or using <literal>deb [signed-by=/etc/apt/keyrings/example-archive-keyring.asc] ...</literal> in the legacy
|
|
<literal>.list</literal> format. This may be useful for APT versions prior to 2.4, which do not
|
|
support embedded keys. ASCII-armored keys must use an extension of <literal>.asc</literal>, and
|
|
unarmored keys an extension of <literal>.gpg</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
To generate keys suitable for use in APT using GnuPG, you will need to use the
|
|
<command>gpg --export-options export-minimal [--armor] --export</command> command.
|
|
Earlier solutions involving <command>--keyring file --import</command> no longer work
|
|
with recent GnuPG versions as they use a new internal format ("GPG keybox database").
|
|
</para>
|
|
|
|
<para>
|
|
Note that a default installation already contains all keys to securely
|
|
acquire packages from the default repositories, so managing keys
|
|
is only needed if third-party repositories are added.
|
|
The <command>extrepo</command> package can be used to manage several
|
|
external repositories with ease.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1><title>Unsigned Repositories</title>
|
|
<para>
|
|
If an archive has an unsigned Release file or no Release file at all
|
|
current APT versions will refuse to download data from them by default
|
|
in <command>update</command> operations and even if forced to download
|
|
front-ends like &apt-get; will require explicit confirmation if an
|
|
installation request includes a package from such an unauthenticated
|
|
archive.
|
|
</para>
|
|
|
|
<para>
|
|
You can force all APT clients to raise only warnings by setting the
|
|
configuration option <option>Acquire::AllowInsecureRepositories</option> to
|
|
<literal>true</literal>. Individual repositories can also be allowed to be insecure
|
|
via the &sources-list; option <literal>allow-insecure=yes</literal>.
|
|
Note that insecure repositories are strongly discouraged and all options
|
|
to force apt to continue supporting them will eventually be removed.
|
|
Users also have the <option>Trusted</option> option available to disable
|
|
even the warnings, but be sure to understand the implications as detailed in
|
|
&sources-list;.
|
|
</para>
|
|
|
|
<para>
|
|
A repository which previously was authenticated but would loose this state in
|
|
an <command>update</command> operation raises an error in all APT clients
|
|
irrespective of the option to allow or forbid usage of insecure repositories.
|
|
The error can be overcome by additionally setting
|
|
<option>Acquire::AllowDowngradeToInsecureRepositories</option>
|
|
to <literal>true</literal> or for Individual repositories with the &sources-list;
|
|
option <literal>allow-downgrade-to-insecure=yes</literal>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1><title>Signed Repositories</title>
|
|
<para>
|
|
The chain of trust from an APT archive to the end user is made up of
|
|
several steps. <command>apt-secure</command> is the last step in
|
|
this chain; trusting an archive does not mean that you trust its
|
|
packages not to contain malicious code, but means that you
|
|
trust the archive maintainer. It's the archive maintainer's
|
|
responsibility to ensure that the archive's integrity is preserved.
|
|
</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 (e.g.) when a maintainer uploads a new
|
|
package or a new version of a package to the Debian archive. In
|
|
order to become effective, this upload needs to be signed by a key
|
|
contained in one of the Debian package maintainer keyrings (available in
|
|
the debian-keyring package). Maintainers' keys are signed by
|
|
other maintainers following pre-established procedures to
|
|
ensure the identity of the key holder. Similar procedures exist in all
|
|
Debian-based distributions.
|
|
</para>
|
|
|
|
<para>
|
|
Once the uploaded package is verified and included in the archive,
|
|
the maintainer signature is stripped off, and checksums of the package
|
|
are computed and put in the Packages file. The checksums 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 for this &keyring-distro; release,
|
|
and distributed alongside the packages and the Packages files on
|
|
&keyring-distro; mirrors. The keys are in the &keyring-distro; archive keyring
|
|
available in the &keyring-package; package.
|
|
</para>
|
|
|
|
<para>
|
|
End users can check the signature of the Release file, extract a checksum
|
|
of a package from it and compare it with the checksum of the package
|
|
they downloaded by hand - or rely on APT doing this automatically.
|
|
</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, malicious
|
|
agents can introduce themselves into 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 propagate malicious
|
|
software to all users downloading packages from that
|
|
host.</para></listitem>
|
|
</itemizedlist>
|
|
|
|
<para>However, it does not defend against a compromise of the
|
|
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>Information changes</title>
|
|
<para>
|
|
A Release file contains beside the checksums for the files in the repository
|
|
also general information about the repository like the origin, codename or
|
|
version number of the release.
|
|
</para><para>
|
|
This information is shown in various places so a repository owner should always
|
|
ensure correctness. Further more user configuration like &apt-preferences;
|
|
can depend and make use of this information. Since version 1.5 the user must
|
|
therefore explicitly confirm changes to signal that the user is sufficiently
|
|
prepared e.g. for the new major release of the distribution shipped in the
|
|
repository (as e.g. indicated by the codename).
|
|
</para>
|
|
</refsect1>
|
|
|
|
|
|
<refsect1><title>Repository Configuration</title>
|
|
<para>
|
|
If you want to provide archive signatures in an archive under your
|
|
maintenance you have to:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem><para><emphasis>Create a toplevel Release
|
|
file</emphasis>, if it does not exist already. You can do this
|
|
by running <command>apt-ftparchive release</command>
|
|
(provided in apt-utils).</para></listitem>
|
|
|
|
<listitem><para><emphasis>Sign it</emphasis>. You can do this by running
|
|
<command>gpg --clearsign -o InRelease Release</command> and
|
|
<command>gpg -abs -o Release.gpg Release</command>.</para></listitem>
|
|
|
|
<listitem><para>
|
|
<emphasis>Publish the key fingerprint</emphasis>, so that your users
|
|
will know what key they need to import in order to authenticate the files
|
|
in the archive. It is best to ship your key in its own keyring package
|
|
like &keyring-distro; does with &keyring-package; to be able to
|
|
distribute updates and key transitions automatically later.
|
|
</para></listitem>
|
|
|
|
<listitem><para>
|
|
<emphasis>Provide instructions on how to add your archive and key</emphasis>.
|
|
If your users can't acquire your key securely the chain of trust described above is broken.
|
|
How you can help users add your key depends on your archive and target audience ranging
|
|
from having your keyring package included in another archive users already have configured
|
|
(like the default repositories of their distribution) to leveraging the web of trust.
|
|
</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
<para>Whenever the contents of the archive change (new packages
|
|
are added or removed) the archive maintainer has to follow the
|
|
first two steps outlined above.</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1><title>See Also</title>
|
|
<para>
|
|
&apt-conf;, &apt-get;, &sources-list;, &apt-ftparchive;,
|
|
&debsign;, &debsig-verify;, &gpg;
|
|
</para>
|
|
|
|
<para>For more background information you might want to review the
|
|
<ulink
|
|
url="https://www.debian.org/doc/manuals/securing-debian-manual/ch07">Debian
|
|
Security Infrastructure</ulink> chapter of the Securing Debian Manual
|
|
(also available 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>
|