**Express Guide to Secure Apt Repositories**

*Copyright © David Love, 2006.*

*Provided under a [Creative Commons Attribution-ShareAlike 2.5 License](http://creativecommons.org/licenses/by-sa/2.5/).*

[Plaintext version](http://www.nighton.net/secure-apt-guide)

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](http://www.nighton.net/archives/mugshot-on-dapper-07-13-2006-156) 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, <code>dists</code>, will contain all of the information about your packages.  The second, <code>pool</code>, 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 <code>m</code> go into the <code>pool/m/</code> directory.  All packages except libraries follow this same first letter / directory rule.  Packages named <code>libm*</code> go into the <code>libm/</code> 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 <code>dists/</code> directory).  To install apt-ftparchive on Ubuntu, you are looking for the *apt-utils* package.

The secret sauce lies in the [ftparchive.conf](http://www.nighton.net/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 <code>deb http://www.nighton.net/ dapper main</code>).  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](http://www.nighton.net/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 <code>source</code>; it is implied.  

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

This is where the final section of the [ftparchive.conf](http://www.nighton.net/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 <code>dists/</code> and <code>pool/</code> in the DocumentRoot of nighton.net, http://www.nighton.net/.  I also provide the <code>nighton_key.asc</code> 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](http://www.debian.org/doc/maint-guide/)
2.  [APT HOWTO](http://www.debian.org/doc/manuals/apt-howto/)
3.  [Debian Repository HOWTO](http://www.debian.org/doc/manuals/repository-howto/repository-howto)
4.  [SecureApt](http://wiki.debian.org/SecureApt)

Corrections, comments, and suggestions are welcome.