Wordpress Plugin for Enigform Authentication - Definitive Guide
AUTHOR: Arturo 'Buanzo' Busleiman <email@example.com>
This document, Enigform, mod_openpgp and wp-enigform-authentication were possible with the invaluable help of OWASP Summer of Code 2008
This page lists all required tasks to get wp-enigform-authentication working, plus all of it's dependencies, both server and client side. You can take this as the only comprehensive Enigform tutorial :)
NOTE: This Wiki Articles is geared towards the Ubuntu GNU/Linux Distribution (and probably Debian and other Debian-based distros). If you can adapt it for Gentoo, Fedora, etc... let me know :)
WINDOWS USERS: Check out the Guide for Installing GnuPG and Enigform on Windows
Table of Contents
On this page... (hide)
First things first: dependencies. Even though this tutorial is geared towards Ubuntu, most packages should be easily available for other distributions. Commands like a2enmod (Apache 2 Enable Module) might differ a lot. For instance, in Gentoo you have to edit /etc/conf.d/apache2 and add, for example "-D PROXY", to enable mod_http_proxy. Refer to the Apache tutorial for your distribution if you need further assistance, or visit http://foros.buanzo.com.ar/viewforum.php?f=35.
Run this command to install (almost) all required dependencies. It's recommended that you
sudo apt-get install apache-dev build-essential libgpg-error-dev libgpgme11-dev python-pysqlite2 sqlite3 subversion gnupg
NOTE: If you get tired of sudo-ing every command, just run
Now, for the next steps, I recommend you become root permanently:
Next, we need to install the pygpgme Python module. A Debian (so, soon Ubuntu) package for pygpgme is about to become available, but in the meantime, follow this procedure:
cd /tmp wget http://pypi.python.org/packages/source/p/pygpgme/pygpgme-0.1.tar.gz cd /usr/src tar -zxvf /tmp/pygpgme-0.1.tar.gz cd pygpgme-0.1 python setup.py build_ext -i python setup.py install
NOTE: There's also a Makefile available for pygpgme-0.1, but it uses python2.4 as default.
Now you can try and see if the pygpgme module gets loaded:
root@murray:/usr/src/pygpgme-0.1# python Python 2.5.2 (r252:60911, Oct 5 2008, 19:24:49) [GCC 4.3.2] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> import gpgme >>> print gpgme <module 'gpgme' from 'gpgme/__init__.py'> >>>
Still as root, we will export a mod_openpgp source tree to a specific directory, like /usr/src/mod_openpgp (adapt as necessary):
cd /usr/src svn export svn://svn.buanzo.org/mod_openpgp ./mod_openpgp cd mod_openpgp
NOTE: If you rather use a stable release, check out Release 0.5.0. You'll need to adapt /usr/src/mod_openpgp as required. TGZ file contains mod_openpgp-0.5.0 folder.
Okay, we are now in /usr/src/mod_openpgp. We can proceed to build mod_openpgp:
The last lines of output should look like this for a successful build:
---------------------------------------------------------------------- Libraries have been installed in: /usr/lib/apache2/modules If you ever happen to want to link against installed libraries in a given directory, LIBDIR, you must either use libtool, and specify the full pathname of the library, or use the `-LLIBDIR' flag during linking and do at least one of the following: - add LIBDIR to the `LD_LIBRARY_PATH' environment variable during execution - add LIBDIR to the `LD_RUN_PATH' environment variable during linking - use the `-Wl,--rpath -Wl,LIBDIR' linker flag - have your system administrator add LIBDIR to `/etc/ld.so.conf' See any operating system documentation about shared libraries for more information, such as the ld(1) and ld.so(8) manual pages. ---------------------------------------------------------------------- chmod 644 /usr/lib/apache2/modules/mod_openpgp.so
NOTE: If you get this output (or similar): cannot open /httpd/build/config_vars.mk: No such file or directory at /usr/sbin/apxs line 201, then it's probably you're getting an empty result from this command: pkg-config --variable=libdir apr-1. This seems to happen on x86_64 machines that have i386 versions of some packages. To fix the issue, simply remove i386 apr-devel and install x86_64 version instead. (Thanks Alex Amiryan for the post at http://alexamiryan.wordpress.com/2009/02/03/problem-with-apxs-under-fedora-7-x86_64/#comment-57)
If you come across an undocumented problem, feel free to visit the forum link at the beginning of this document.
Now we can proceed to copy the file that actually loads mod_openpgp.so in Apache, and the EPS proxy. Make sure you are root and your current directory is still /usr/src/mod_openpgp, then:
cp docs/99_mod_openpgp.load /etc/apache2/mods-available cp eps/eps.py /usr/local/bin chmod +x /usr/local/bin/eps.py
With those files in place, the next necessary step is to enable the 99_mod_openpgp and proxy_http modules:
a2enmod 99_mod_openpgp a2enmod proxy_http
Congratulations! We can now proceed to the next item on our TODO list, which is...
Before creating or importing ANY key (Server or Client) I recommend you take a moment to install the NTP client ntpdate. You only need to run
Ubuntu usually comes with GnuPG (The GNU Privacy Guard, the GREAT free/libre open-source, GPL-ed implementation of the OpenPGP Standard. Long life to Werner Koch. You and the gnupg-devel team ROCK!). In our case, we already included gnupg in the apt-get install command at the beginning of this document.
The user Apache runs as is www-data (for standard setups, if you ahve a more advanced setup you probably don't even need me to tell you this). The home directory for www-data is usually /var/www. For some strange reason, sometimes /var/www is not owned by www-data. Let's make sure of that.
chown www-data:www-data /var/www
Now we can proceed to creating our GnuPG Keypair. We need to run this command:
su - www-data --shell=/bin/bash -c "gpg --gen-key"
NOTE: The Ubuntu Team has a GREAT tutorial for the gpg --gen-key command. Once you've run it (remember, use the above command, as the keypair must be created for the www-data user!), open this link on another tab and review it.
Basicly, you just need to create your keypair just like in the previous step. Once you've created it, run this command to obtain the 16-character Long KeyID that is needed to configure wp-enigform-authentication:
gpg -K --keyid-format long
For example, this is what the output looks like in one of my test users:
test2@murray:~$ gpg -K --keyid-format long /home/test2/.gnupg/secring.gpg ------------------------------ sec 1024D/7F5D975850C23A12 2009-03-13 uid test2 (test2) <firstname.lastname@example.org> ssb 2048g/44CAAF149F5D5AEA 2009-03-13
In the above example, the Long KeyID is 7F5D975850C23A12. In your case this number will be DIFFERENT!
Now, we need to send this key to a Key Server. You will need to adapt the next command to suit your Long KeyID. In the following example, we'll use the Long KeyID
gpg --keyserver hkp://wwwkeys.eu.pgp.net --send-keys 7F5D975850C23A12
NOTE: Replace the 7F5D975850C23A12 Long KeyID with *YOURS*.
Once the key has been sent to a keyserver, we should become www-data on the server, then we will import this key from the same keyserver. If the key is not received on the first try, wait a few seconds and try again:
gpg --keyserver hkp://wwwkeys.eu.pgp.net --recv-keys 7F5D975850C23A12
Running EPS is very simple. First of all, let's make a test-run:
It should show this output:
Enigform Session Database OK. EPS has started. Listening on port 2280.
If that's the case, press now CTRL-C. You should return to the # prompt. We can now add this command to /etc/rc.local:
After editing, /etc/rc.local might look like this:
#!/bin/sh -e # # rc.local # # This script is executed at the end of each multiuser runlevel. # Make sure that the script will "exit 0" on success or any other # value on error. # # In order to enable or disable this script just change the execution # bits. # # By default this script does nothing. su - www-data -c /usr/local/bin/eps.py >/dev/null 2>&1 & exit 0
Now EPS will start automatically upon reboot. But let's make it run NOW, by using this command:
su - www-data -c /usr/local/bin/eps.py >/dev/null 2>&1 &
As you can see, both the stdout and stderr outputs have been redirected to /dev/null. If you rather redirect them to files, you should know that stdout shows what is happenning right now with EPS (Encrypting a session hash, etc), and stderr is a standard Apache-like HTTP log.
This is an example VirtualHost with EPS and mod_openpgp configured. You'd place this VirtualHost in /etc/apache2/sites-available/default. It's the actual VirtualHost configuration for my blog, http://blogs.buanzo.com.ar, which of course has wp-enigform-authentication:
<VirtualHost *:80> ServerName blogs.buanzo.com.ar DocumentRoot /var/www/blogs.buanzo.com.ar/htdocs ErrorLog /var/www/blogs.buanzo.com.ar/logs/error_log CustomLog /var/www/blogs.buanzo.com.ar/logs/access_log combined <IfModule mod_openpgp.c> # In gentoo, you'd probably use <IfDefine OPENPGP>...</IfDefine> # Turn on the OpenPGP Engine for this VirtualHost OpenPGPEngine on OpenPGPHomeDir /var/www/.gnupg </IfModule> <IfModule mod_proxy_http.c> ProxyRequests Off SetEnv force-proxy-request-1.0 1 SetEnv proxy-nokeepalive 1 SetEnv proxy-sendcl 1 <Proxy *> Order deny,allow Allow from all </Proxy> # EPS listens by default on 127.0.0.1 port 2280/tcp ProxyPass /HTTP_OPENPGP_DISCOVERY http://127.0.0.1:2280/HTTP_OPENPGP_DISCOVERY ProxyPassReverse /HTTP_OPENPGP_DISCOVERY http://127.0.0.1:2280/HTTP_OPENPGP_DISCOVERY ProxyPass /HTTP_OPENPGP_BEGIN_SESSION http://127.0.0.1:2280/HTTP_OPENPGP_BEGIN_SESSION ProxyPassReverse /HTTP_OPENPGP_BEGIN_SESSION http://127.0.0.1:2280/HTTP_OPENPGP_BEGIN_SESSION ProxyPass /HTTP_OPENPGP_END_SESSION http://127.0.0.1:2280/HTTP_OPENPGP_END_SESSION ProxyPassReverse /HTTP_OPENPGP_END_SESSION http://127.0.0.1:2280/HTTP_OPENPGP_END_SESSION </IfModule> </VirtualHost>
In step 3 we created a Keypair. With the same user account we should now proceed to install the Enigform plugin (version 0.8.3.1 or higher) into Firefox. For this, proceed to the Mozilla Addons page for Enigform and click 'Add to Firefox'.
After installing the plugin, Firefox will ask you to restart the browser. Do it.
When restarted, proceed to Tools -> Addons -> Enigform -> Preferences and configure it. If you have a GnuPG Agent available, click 'use GPG Agent'. If you have multiple signing keys, input the KeyID for the one you wish to use. In the Tools menu you will also find an 'Enigform Debug Info' option: it might become handy if you seek support in the Forums.
I recommend you visit the mod_openpgp testing site as soon as possible and play a little bit with it.
NOTE: If you install Enigform in a user account that does not have an OpenPGP Keypair available, Enigform will notice that and disable itself.
You can download the wordpress plugin from: http://wordpress.org/extend/plugins/wp-enigform-authentication/
Now save your changes, make sure everything is in place, and click the 'Enigform Login' link. The passphrase to unlock your private key should be requested. Depending on your setup (with/without a GnuPG Agent) the passphrase might be requested two times in a row. And then you will be logged in as administrator. Remember to visit Buanzo's Enigform Forum if you come across any problems.
Thanks for supporting this experimental technology!