All about secure apt

Recently Debian's unstable and testing branches have begun to use strong crypto to validate downloaded packages. This is commonly called "secure apt" and was implemented in version 0.6. Since the documentation is fairly slim on how this all works from an administrator's point of view, this document will try to explain in detail how it secure apt works and how to use it.


Basic concepts

Here are a few basic concepts that you'll need to understand for the rest of this document.

A checksum is a method of taking a file and boiling it down to a reasonably short number that uniquely identifies the content of the file. This is a lot harder to well than it might seem, and the most commonly used type of checksum, the md5sum, is in the process of being broken.

Public key cryptography is based on pairs of keys, each consisting of one public key and one private key. The public key is given out to the world; the private key must be kept a secret. Anyone possessing one key can encrypt a message so that it can only be read by someone possessing the other key. It's also possible to use a key to only sign a file, not encrypt it. If a private key is used to sign a file, then anyone who has the public key can check that the file was signed by that key. No one who doesn't have the private key can forge such a signature.

These keys are quite long numbers (1024 to 2048 digets or more long), and to make it easier to work with them they have a key id, which is a shorter, 8 or 16 diget number that can be used to refer to them.

gpg is the tool used in secure apt to sign files and check their signatures.

apt-key is a program that is used to manage a keyring of gpg keys for secure apt. The keyring is kept in the file /etc/apt/trusted.gpg (not to be confused with the related but not very interesting /etc/apt/trustdb.gpg). apt-key can be used to show the keys in the keyring, and to add or remove a key.

Secure apt groundwork: checksums

A Debian archive contains a Release file, which is updated each time any of the packages in the archive change. Amoung other things, the Release file contains some md5sums of other files in the archive. An excerpt of an example Release file:

 6b05b392f792ba5a436d590c129de21f            3453 Packages
 1356479a23edda7a69f24eb8d6f4a14b            1131 Packages.gz
 2a5167881adc9ad1a8864f281b1eb959            1715 Sources
 88de3533bf6e054d1799f8e49b6aed8b             658 Sources.gz

(The Release files also include sha1 checksums, which will be useful once md5sums become fully broken, however apt doesn't use them yet.)

Now if we look inside a Packages file, we'll find more md5sums, once for each package listed in it. For example:

Package: uqm
Priority: optional
Filename: unstable/uqm_0.4.0-1_i386.deb
Size: 580558
MD5sum: 864ec6157c1eea88acfef44d0f34d219

These two checksums allow apt to verify that it's downloaded a correct copy of the Packages file, with a md5sum that matches the one in the Release file. And when it downloads an individual package, it can also check its md5sum against the content of the Packages file. If apt fails at either of these steps, it will abort.

None of this is new in secure apt, but it does provide the foundation. Notice that so far there is one file that apt doesn't have a way to check: The Release file. Secure apt is all about making apt verify the Release file before it does anything else with it, and plugging this hole, so that there is a chain of verification from the package that you are going to install all the way back to the provider of the package.

Signed Release files

To plug the hole, secure apt adds a gpg signature for the Release file. This is put in a file named Release.gpg that's shipped alongside the Release file. It looks something like this, although only gpg actually looks at its contents normally:

Version: GnuPG v1.4.1 (GNU/Linux)


(Technically speaking, this is an ascii-armored detached gpg signature.)

How apt uses Release.gpg

Secure apt always downloads Release.gpg files when it's downloading Release files, and if it cannot download the Release.gpg, or if the signature is bad, it will complain, and will make note that the Packages files that the Release file points to, and all the packages listed therin, are from an untrusted source. Here's how it looks during an apt-get update:

W: GPG error: testing Release: The following signatures
 couldn't be verified because the public key is not available: NO_PUBKEY 0109083

Note that the second half of the long number is the key id of the key that apt doesn't know about, in this case that's 2D230C5F.

If you ignore that warning and try to install a package later, apt will warn again:

WARNING: The following packages cannot be authenticated!
  libglib-perl libgtk2-perl
Install these packages without verification [y/N]?

If you say Y here you have no way to know if the file you're getting is package you're supposed to install, or if it's something else entirely that a black hat has arranged for you, containing a nasty suprise.

Note that you can diable these checks by running apt with --allow-unauthenticated.

It's also worth noting that newer versions of the Debian installer use the same signed Release file mechanism during their debootstap of the Debian base system, before apt is available, and that the installer even uses this system to verify peices of itself that it downloads from the net. Also, Debian does not currently sign the Release files on its CDs; apt can be configured to always trust packages from CDs so this is not a large problem.

How to tell apt what to trust

So the security of the whole system depends on there being a Release.gpg file, which signs a Release file, and of apt checking that signature using gpg. To check the signature, it has to know the public key of the person who signed the file. These keys are kept in apt's own keyring (/etc/apt/trusted.gpg), and managing the keys is where secure apt comes in.

By default, Debian systems come preconfigured with the Debian archive key in the keyring.

joey@dragon:~>sudo apt-key list
pub   1024D/4F368D5D 2005-01-31 [expires: 2006-01-31]
uid                  Debian Archive Automatic Signing Key (2005) <ftpmaster@debi>

Here 4F368D5D is the key id, and notice that this key was only valid for a one year period. Debian rotates these keys as a last line of defense against some sort of security breach breaking a key.

That will make apt trust the official Debian archive, but if you add some other apt repository to /etc/apt/sources.list, you'll also have to give apt it's key if you want apt to trust it. Once you have the key and have verified it, it's a simple matter of "apt-key add file" to add it. Getting the key and verifying it are the trickier part.

How to find a key

There is not yet a standard location where you can find the key for a given apt repository. There's a rough standard of putting the key up on the web page for the repository or as a file in the repository itself, but no real standard, so you might have to hunt for it.

The Debian archive signing key is available at (replace 2006 with current year). (Nobody seems to be telling what "ziyi" means.)

gpg itself has a standard way to distribute keys, using a keyserver that gpg can download a key from and add it to its keyring. For example:

joey@dragon:~>gpg --keyserver --recv-key 2D230C5F
gpg: requesting key 2D230C5F from hkp server
gpg: key 2D230C5F: public key "Debian Archive Automatic Signing Key (2006) <ftpm>" imported
gpg: Total number processed: 1
gpg:               imported: 1

You can then export that key from your own keyring and feed it to apt-key:

joey@dragon:~>gpg -a --export 2D230C5F | sudo apt-key add -
gpg: no ultimately trusted keys found

(What does the "gpg: no ultimately trusted keys found" warning mean?)

How to safely add a key

By adding a key to apt's keyring, you're telling apt to trust everything signed by the key, and this lets you know for sure that apt won't install anything not signed by the person who possesses the private key. But if you're sufficiently paranoid, you can see that this just pushes things up a level, now instead of having to worry if a package, or a Release file is valid, you can worry about whether you've actually gotten the right key. Is the mentiond above really Debian's archive signing key, or is this document a clever trap?

It's good to be paranoid in security, but verifying things from here is harder. gpg has the concept of a chain of trust, which can start at someone you're sure of, who signs someone's key, who signs some other key, etc until you get to the archive key. If you're sufficiently paranoid you'll want to check that your archive key is signed by a key that you can trust, with a trust chain that goes back to someone you know personally. If you want to do this, visit a Debian conference.

(Note: Not all apt repoisitory keys are signed at all by another key. Maybe the person setting up the repository doesn't have another key, or maybe they don't feel comfortable signing such a role key with their main key.)

If you can't afford this level of paranoia, do whatever feels appropriate to you when adding a new apt source and a new key. Maybe you'll want to mail the person providing the key and verify it, or maybe you're willing to take your chances with downloading it and assuming you got the real thing. The important thing is that by reducing the problem to what archive keys to trust, secure apt lets you be as careful and secure as it suites you to be.

Debian archive key yearly rotation

As mentioned above, the Debian archive signing key is changed each year, in January. Since secure apt is young, we don't have a great deal of experience with changing the key and there are still rough spots.

In January 2006, a new key for 2006 was made and the Release file began to be signed by it, but to try to avoid breaking systems that had the old 2005 key, the Release file was signed by that as well. The intent was that apt would accept one signature or the other depending on the key it had, but apt turned out to be buggy and refused to trust the file unless it had both keys and was able to check both signatures. This was fixed in apt version There was also confusion about how the key was distributed to users who already had systems using secure apt; initially it was uploaded to the web site with no announcement and no real way to verify it and users were forced to download it by hand.

Based on this experience, here's how things could work in 2007:

But it's really too early to tell.

Setting up a secure apt repository


Comments and questions

(Add any here.)

This document is copyright 2006 JoeyHess and others under the terms of the GNU GPL.