• View
• Edit
• History
• Print

Wordpress Plugin for Enigform Authentication - Definitive Guide

AUTHOR: Arturo 'Buanzo' Busleiman <[email protected]>

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

1.  Mod_Openpgp Installation: Dependencies, mod_openpgp and EPS

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 apt-get update && apt-get upgrade your system before installing anything else:

 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 sudo /bin/bash to fire up a root shell.

Now, for the next steps, I recommend you become root permanently: sudo /bin/bash

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:

 ./build.sh

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...

2.  Server Keypair Creation

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 apt-get install ntpdate - But I also recommend you take a look at this article.

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.

3.  Client Keypair Creation and Import into Server's Keyring

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) <[email protected]>
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

4.  Running EPS (Enigform Python Server)

Running EPS is very simple. First of all, let's make a test-run:

 /usr/local/bin/eps.py

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: su - www-data -c /usr/local/bin/eps.py >/dev/null 2>&1 & BEFORE the last line, which says 'exit 0'.

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.

5.  Apache VirtualHost Configuration for EPS and mod_openpgp

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>

6.  Installing Enigform in your Firefox Browser

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.

7.  Wordpress Plugin Installation and Configuration

You can download the wordpress plugin from: http://wordpress.org/extend/plugins/wp-enigform-authentication/

1. Upload the wp-enigform-authentication.php file to your wp-contents/plugins folder.
2. Open your Enigform-enabled Firefox browser. Visit http://maotest.buanzo.org to test it before proceeding.
3. Login to your administrator's control panel, then activate the plugin.
4. Proceed to the Settings page for Enigform Authentication. Input the Long KeyID you obtained in step 3 (Client Key Creation). This way the plugin can detect you are the administrator. Be very careful with this step!. If you don't correctly configure the KeyID you won't be able to login as administrator. USE the maotest.buanzo.org enigform test site.
5. Save the settings

8.  Wordpress Template Editing

To fully enable Enigform, you need to add a special 'Enigform Login' link, plus a very short snippet of javascript in the same page. If you take a look at Buanzo's Blog's index page source code you'll notice the 'Enigform Login' link on the sidebar at the right. Edit your wordpress template, or add an html widget. Whatever works best for your blog. This is the code you must add:

<script>
function enigform_begin_session(realm,duration) {
	var event = document.createEvent("Events");
	event.initEvent("evtEnigform_Begin_Session", true, false);
        // Still not implemented.
	//        document.body.setAttribute('Realm', realm);
	//        document.body.setAttribute('Duration', duration);
	document.dispatchEvent(event);
}
</script>
<a href="/wp-login.php##ENIGFORM_Sign##" onclick="javascript:enigform_begin_session('Realm',300)" name="OpenPGPLoginElement">Enigform Login</a>

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!