

    Read this file to get some information on how to enable (GnuPG)
    signature verification and automatic archive signing.

  
  1. Change home directory for user debarchiver (optional)
  2. Create GnuPG infrastructure
  3. Enable GnuPG signature verification
  4. Create a primary key
  5. Create an archive signing key
  6. Enable GnuPG archive signing
  7. Clean-up
  8. Known problems


($ means user-shell, # means root-shell)

1. Change home directory for user debarchiver (optional):
---------------------------------------------------------

This first point is optional, but it is based on my experiences. The thoughts:
We will create a .gnupg sub-directory and the devscripts config file
.devscripts in debarchiver's home directory. Now it is possible, that you make
your repository public (read README.web). Maybe you share my opinion, that
guests looking at your website should not have access to these files. There
are 3 ways to prevent them to access .gnupg or .devscripts:

 - see README.repository for entry to make in httpd.conf/vhosts.conf or
   don't make /var/lib/debarchiver public
 
 - move your repository into a sub-directory of /var/lib/debarchiver (e.g.
   /var/lib/debarchiver/archive) and make this sub-directory public
   
   	# cd /var/lib/debarchiver
   	# mkdir archive
   	# mv dists archive/
   	# mv incoming archive/
   	# vi /etc/debarchiver.conf
   	  -> fix '$destdir' and '$inputdir'

 - change the home directory for debarchiver to e.g. /home/debarchiver
 	
 	# mkdir /home/debarchiver
 	# chown debarchiver.debarchiver /home/debarchiver
 	# usermod -d /home/debarchiver debarchiver
 
I prefer the last alternative, because this is IMHO the cleanest solution. But
decide at your own.


2. Create GnuPG infrastructure:
-------------------------------

First, we will give debarchiver temporary access to /bin/bash and login as
debarchiver:

	# chsh -s /bin/bash debarchiver
	# su debarchiver
	$ cd ~

The next step creates the GnuPG infrastructure (maybe you need to run this
command twice):

	$ echo -n "" | gpg

Optional, but recommended: Comment out all keyservers in
~debarchiver/.gnupg/gpg.conf.

Now we have the necessary infrastructure and we can begin to import keys:

	$ gpg --no-default-keyring --keyring uploaders.gpg \
		--import <keyfile>
	
	or
	
	$ gpg --no-default-keyring --keyring uploaders.gpg \
		--keyserver <server> --recv-keys <key ID>

Now we need to make dscverify recognize our keyring uploaders.gpg:

	$ cp /etc/devscripts.conf ~/.devscripts
	$ vi .devscripts
	  -> uncomment DSCVERIFY_KEYRINGS and add our keyring:
	     DSCVERIFY_KEYRINGS="~/.gnupg/uploaders.gpg"
	  [save&exit]


A first test will show, if everything works as expected. Therefor upload a
signed package into $incomingdir and run dscverify. The output should be:

	$ dscverify <package>.changes
	    <package>.changes:
	        Good signature found
	    validating <package>.dsc
	        Good signature found
	    validating <package>.orig.tar.gz
	    validating <package>.diff.gz
	    validating <package>.deb
	    All files validated successfully.


3. Enable GnuPG signature verification:
---------------------------------------

To enable the verification of signed package files:

	# vi /etc/debarchiver.conf
	  -> $vrfycmd = "dscverify";
	  -> $verifysignatures = 1;
	  -> $verifysignaturesdistinput = 1;
	  [save&exit]

Now you should test your repository and upload a signed package.

If you're only using GnuPG signature verification, you can stop here and go to
7. Clean-ups.


4. Create a primary key:
------------------------

NOTE: You don't want to use this key to sign the Release files. We will
create the archive signing key one step later.

NOTE: You can skip this step if you are running debarchiver on your own
account and if you already have a primary key.

	$ gpg --gen-key


5. Create an archive signing key:
---------------------------------

To sign an archive (the Release files) as written in 'man apt-secure' and
http://www.debian.org/doc/manuals/securing-debian-howto/ch7#s7.4.1, we will
need to create a GnuPG key-pair and tell debarchiver to use this key (and
passphrase) to sign our archive (see 6.). 

	$ gpg --gen-key

The passphrase (if existent) needs to stored in a file, which is set to
permissions 0600. Of course this violates traditional practice. But there is
no other way of an automatic Release signing mechanism. The default file
is ~/.gnupg/passphrase.

	$ touch ~/.gnupg/passphrase
	$ chmod 600 ~/.gnupg/passphrase
	$ vi ~/.gnupg/passphrase
	  -> Enter passphrase
	  [save$exit]


6. Enable GnuPG archive signing:
--------------------------------

To enable automatic archive signing:

	# vi /etc/debarchiver.conf
	  -> $gpgkey = "MY_ARCHIVE_SIGNING_KEY";
	     (replace MY_ARCHIVE_SIGNING_KEY with the appropriate value)
	  -> $gpgpassfile = "$ENV{HOME}/.gnupg/passphrase";
	     (only if you use a key with a non-empty passphrase, the file
	      above is the default value -> adjust it if necessary)
	    -OR-
	     $gpgpassfile = ""; -OR- $gpgpassfile = 0;
	     (for an empty passphrase)

Next time debarchiver is run, it will create Release.gpg files. In this case,
you should upload your public archive signing key to a server to make it
available to the public.


7. Clean-up:
-----------------

If everything works, we are ready to continue. Logout from debarchiver shell:

	$ exit

We can now remove the access to /bin/bash for debarchiver:

	# chsh -s /bin/false debarchiver

Optional: Remove .bash_history and .viminfo from ~debarchiver/

	# rm ~debarchiver/.bash_history ~debarchiver/.viminfo


8. Known problems:
------------------

If you changed the home-directory for debarchiver, it sometimes can happen,
that it will still not work. In this case make sure, that you followed all
steps as described above and then run:

	# usermod -d /var/lib/debarchiver debarchiver
	# usermod -d /home/debarchiver

Now it should work.

In every other cases: Make sure, that you followed all steps as described
above.

