Express Guide to Secure Apt Repositories

Express Guide to Secure Apt Repositories

Copyright © David Love, 2006.

Provided under a Creative Commons Attribution-ShareAlike 2.5 License.

In it’s simplest form, updating a secure apt repository takes only five steps. As an example, let’s use mugshot as a package:

	$  mv mugshot_1.1.13-1_amd64.deb mugshot_1.1.13-1.dsc 
		mugshot_1.1.13-1.diff.gz  
		mugshot_1.1.13.orig.tar.gz 
		/home/dlove/Software/apt-repository/pool/m/

	$  cd /home/dlove/Software/apt-repository/

	$  apt-ftparchive generate ftparchive.conf

	$  apt-ftparchive -c ftparchive.conf release 
		dists/dapper > dists/dapper/Release

	$  gpg --sign -ba -o dists/dapper/Release.gpg 
		dists/dapper/Release

Now, for a slightly longer explanation.

This guide assumes you have a pre-existing gpg key. In order for apt to recognize the signature of the secure repository, you’ll need to export the ascii-armored version of your public key. In my case:

	$  gpg -a --export dlove@nighton.net > nighton_key.asc

Place this somewhere publicly available so that users of the repository can add it to the list of keys that apt recognizes. You may wish to look at my repository adding instructions for nighton.net to see an example of that process.

	$  mv mugshot_1.1.13-1_amd64.deb mugshot_1.1.13-1.dsc 
		mugshot_1.1.13-1.diff.gz  
		mugshot_1.1.13.orig.tar.gz 
		/home/dlove/Software/apt-repository/pool/m/

Apt, being a varied and versatile tool offers many possible directory structures. So many, in fact, that when trying to learn how to setup a repository, I was thoroughly and utterly confused. 🙂

Instead of trying to explain all that, I’ll just present one of the many possible ways to organize your files.

In my (dlove’s) home directory, I have a folder named Software for managing various software building/packaging tasks. One of the folders beneath this represents the root of my apt-repository. It is creatively named, apt-repository.

	->  home
		->  dlove
			->  Software
				->  apt-repository

Within the root of the apt-repository lie two subfolders. The first, dists, will contain all of the information about your packages. The second, pool, will contain the actual files for download themselves (.deb packages, as well as the source files). For mugshot, I build packages targeted at Ubuntu dapper for both the i386 and amd64 architecture. Hence, my apt-repository looks like the following:

	->  apt-repository
		->  dists
			->  dapper
				->  main
					->  binary-amd64
					->  binary-i386
					->  source
		->  pool
			->  m

Packages beginning with the letter m go into the pool/m/ directory. All packages except libraries follow this same first letter / directory rule. Packages named libm* go into the libm/ directory.

	$  cd /home/dlove/Software/apt-repository/

All of the steps from this point forward take place in the root of the apt-repository.

	$  apt-ftparchive generate ftparchive.conf

This is the magic incantation I was searching for. The deceptively named apt-ftparchive is an extremely useful tool for automagically generating all of the various files that provide the description information (all of the stuff under the dists/ directory). To install apt-ftparchive on Ubuntu, you are looking for the *apt-utils* package.

The secret sauce lies in the ftparchive.conf file. Let’s break this puppy down:

	Dir {
		ArchiveDir "/home/dlove/Software/apt-repository/";
		CacheDir  "/home/dlove/Software/apt-repository/";
	};

These two lines should list the root of your apt-repository. The CacheDir line allows apt-ftparchive to cache information about your packages between runs. On large repositories, this can speed up archive generation.

	TreeDefault {
		Directory		"pool/";
		SrcDirectory		"pool/";
	};

When generating the repository information, apt-ftparchive will look under these directories (and all subdirectories) for binary and source files respectively.

	Tree "dists/dapper" {
		Sections		"main";
		Architectures		"amd64 i386 source";
	};

By now, you should be noticing a pattern. All of these configuration lines map to the directory structure of the repository.

	->  apt-repository
		->  dists
			->  dapper
				->  main
					->  binary-amd64
					->  binary-i386
					->  source
		->  pool
			->  m

I am targeting dapper as my distribution. My software is in the main section (hence the sources.list line deb http://www.nighton.net/ dapper main). I am providing packages for amd64, i386, and source. NOTE: If you are distributing GPL software, the terms of the GPL require you to provide the source archive as well as the binary .deb files.

The final part of the ftparchive.conf file describes you the distributor, as well as what type of packages you are providing.

	APT::FTPArchive {
		Release {
			Origin			"http://www.nighton.net/";
			Label			"(=) ( nighton . net )";
			Suite			"dapper";
			Version			"6.06";
			Codename		"dapper";
			Architectures		"amd64 i386";
			Components		"main";
			Description		"Packaged by David Love.";
		};
	};

You will want to change the origin to your repository root. Label and Description can be any generally descriptive text about you. For Architectures, it is not necessary to list source; it is implied.

	$  apt-ftparchive -c ftparchive.conf release 
		dists/dapper > dists/dapper/Release

This is where the final section of the ftparchive.conf file is used. The Release file forms the basis of secure apt. By offering checksums of the descriptive files Packages.gz and Sources.gz, which in turn provide checksums of all of the binary and source files, the Release file offers us a way of verifying whether or not corruption has occurred in any of the packages. But only if we can trust the Release file…

	$  gpg --sign -ba -o dists/dapper/Release.gpg 
		dists/dapper/Release

The final step in secure apt is to digitally sign the Release file. By checking the signature of the Release file against the ascii-armored public key, apt can verify whether or not any of the packages it wishes to install have been corrupted in a secure fashion (i.e., knowing that the Release file can be trusted).

Now that you have a complete secure apt repository built on your local machine, you will probably want to provide access to it somewhere a little less locally. For the following sources.list lines:

	deb http://www.nighton.net/ dapper main
	deb-src http://www.nighton.net/ dapper main

I place the dists/ and pool/ in the DocumentRoot of nighton.net, http://www.nighton.net/. I also provide the nighton_key.asc in the same location for convenience.

Congratulations!

You should now have a functional secure apt repository. Remember, apt is a far more versatile tool than this guide demonstrates. In order to go further, I suggest the following resources:

1. Debian New Maintainers’ Guide
2. APT HOWTO
3. Debian Repository HOWTO
4. SecureApt

Corrections, comments, and suggestions are welcome.

Advertisements

9 thoughts on “Express Guide to Secure Apt Repositories

  1. Unfortunately, I don’t have the hardware to directly build ppc packages. If I get some time this weekend I’ll look at setting up a cross-compiler environment in order to pull this off.

  2. Not a problem. I’ve actually been looking to get more involved in the community again, however, I have been sicker than a dog the last couple of days. Bleh. I’ve got the basics of a guide for creating a pbuilder environment and streamlining the entire process of build -> distribute. Going to finish it one of these days. 🙂

    Side note: anyone have some first-hand experience with migrating from a self-hosted repository to one of the ppas?

  3. Pingback: Introducing kernel.nighton.net | (=) ( nighton . net )

  4. Pingback: Mugshot On Dapper | (=) ( nighton . net )

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s