mod_auth_openpgp - README FOR v0.2.1
by Arturo 'Buanzo' Busleiman <buanzo@buanzo.com.ar>
Official Forum at: http://foros.buanzo.com.ar/viewforum.php?f=35

Licensed under the Apache License 2.0

Quick-Building instructions:

/path/to/apxs2 -c -i -l gpgme -l gpg-error -I /usr/include/gpgme mod_auth_openpgp.c

Adapt your paths as needed. I'm using gpgme 1.1.2 and libgpg-error 1.0
(there are newer versions, but those are the 'stable' ones for Gentoo x86).

I'll provide better instructions as soon as people start providing feedback.

Load it into Apache with:

<IfModule !mod_auth_openpgp.c>
	LoadModule auth_openpgp_module    modules/mod_auth_openpgp.so
</IfModule>

Then, turn it on for specific virtual hosts (or server globally) using the
"OpenPGPEngine on" command and with mod_access directives, for example:

<VirtualHost *:80>

ServerName localhost
ServerAdmin root@localhost
DocumentRoot "/var/www/localhost/htdocs"
Options FollowSymlinks
	
<IfModule mpm_peruser_module>
	ServerEnvironment apache apache
</IfModule>

# Turn on the OpenPGP Engine for this VirtualHost
OpenPGPEngine on

# To Allow user buanzo@buanzo.com.ar use SetEnvIf like this:
# If the X-Auth-OpenPGP-Email header begins with the buanzo@buanzo.com.ar value,
# then set the valid_user env var to be used as
# decisive factor in the Allow sentence of mod_access.
# X-Auth-OpenPGP* headers cannot be spoofed, as they get resetted
# if the module has been enabled for the vhost.

SetEnvIf X-Auth-OpenPGP-Email buanzo@buanzo.com.ar valid_user
<Directory "/var/www/localhost/htdocs/pba">
	Order Deny,Allow
	Deny from all
	Allow from env=valid_user
</Directory>

</VirtualHost>

This is a list of available X-Auth-OpenPGP headers for a valid signed
request:

X-Auth-OpenPGP = true
X-Auth-OpenPGP-Fingerprint = 7350B06E7AEA78FDE739F3AD025A4EB06857704D
X-Auth-OpenPGP-Email = buanzo@buanzo.com.ar
X-Auth-OpenPGP-Name = Arturo Alberto Busleiman
X-Auth-OpenPGP-Comment = aka Buanzo

Of course, you can also use the module just to verify requests for a certain
vhost (or Location/Directory in the FUTURE...), then use PHP, Ruby,
mod_perl, etc to check for those headers from within your site.

Additionally, you can announce that your virtualhost supports OpenPGP by
adding this block to your virtualhost config:

        <Location /HTTP_OPENPGP_DISCOVERY>
                SetHandler mao_Discovery
        </Location>

Once I finish implementing the mao_ImportKey handler, clients (like
Firefox+Enigform) will be able to ask your server to import their public key
automagically. Just for the record, the Location-SetHandler block will look
like this:

        <Location /HTTP_OPENPGP_IMPORTKEY>
                SetHandler mao_ImportKey
        </Location>

mao_ImportKey will be implemented in 0.2.2. In any case, I've also added a
new Apache config command, used to declare which KeyServer will be used to
import openpgp keys. If it is not provided, it gets a default value of
"hkp://subkeys.pgp.net".

OpenPGPKeyServer hkp://subkeys.pgp.net

Sincerely,
Arturo 'Buanzo' Busleiman
buanzo at buanzo com ar
