Pubcookie Apache Module - Install Guide

Note: Documentation can contain bugs too. Use the online version of this document for the most up-to-date information.

Included on this page:

Overview

This guide helps Apache HTTP server administrators install and use the Pubcookie Apache module, herein referred to as simply the module, but also commonly known as mod_pubcookie.

The topics covered below will help you to :

Site administrators should refer to the login server guide for instructions on deploying a Pubcookie login server.

What's New

Significant improvements and changes included in Pubcookie 3.3.2c:

Significant improvements and changes included in Pubcookie 3.3.2b:

Significant improvements and changes included in Pubcookie 3.3.2a:

Significant improvements and changes included in Pubcookie 3.3.2:

Significant improvements and changes included in Pubcookie 3.3.1:

Significant improvements and changes included in Pubcookie 3.3.0a:

Significant improvements and changes included in Pubcookie 3.3.0:

See doc/CHANGES.txt for bug fixes and other improvements.

Compatibility Notes

Here are some compatibility notes for version 3.3:

Compatibility note on version 3.3 encryption algorithms:
The version 3.3 module supports different encryption algorithms. AES encryption is the default. However, earlier versions of the login server only support one algorithm, DES, so you will have to determine the version of your login server and configure the PubcookieEncryption directive accordingly.
Compatibility note on version 3.1 relays:
The need for the cgi-based relays introduced in version 3.1 to authenticate across DNS domains was redressed by the POST-based messaging method introduced in version 3.2. Use of third-party 3.1 relays has therefore been deprecated. A third-party relay is any relay not hosted on the same server that requests authentication. Application servers using third-party relays are strongly encouraged to upgrade to version 3.2 or higher and use the POST-based messaging method.

Upgrading

In general (note exceptions below) upgrading a working installation of the module requires very few, if any, changes to the current Apache configuration, and you can typically reuse your current Pubcookie granting certificate and symmetric encryption key too.

Here are some compatibility notes for upgrading between specific versions:

Upgrading from version 3.0/3.1/3.2 to 3.3:
Apache servers being upgraded from version 3.0/3.1/3.2 to version 3.3 should be aware that version 3.3 expects and uses AES encryption by default. If your login server is version 3.3 or higher, interoperability isn't a concern. However, to interoperate with earlier version of login server, you should configure PubcookieEncryption to use DES encryption, or, if you don't want to make any Apache configuration changes, you should build the module using the --enable-default-des configure option, which forces the module to use DES encryption by default.

If your login server is version 3.3 higher and therefore allows you to use AES encryption, you should note that session cookies encrypted with DES cannot be unencrypted with AES. As a result, pre-session and session cookies obtained by users prior to upgrading the module will be invalid after the upgrade. Therefore, some users will be redirected through the login server to establish a new session.

Clustered hosts should be upgraded with special care to keep all cluster members using the same encryption method.

Note: You do not have to request a new encryption key to use version 3.3. Your current host key works equally well for AES and DES encryption.

Upgrading from version 1.77 to 3.3:
Apache servers being upgraded from earlier versions of the module (classic versions, such as version 1.77) may require minor configuration changes. Review the Apache configuration section closely. Also review the sections on virtual host configuration and clustered host configuration if they apply to your environment.

Apache servers being upgraded from earlier versions should also be aware of the switch to AES encryption noted in the section above.

Also recall that version 1.77 requires an encryption key specific to your primary IP address. If you want to be able to rollback to version 1.77 more easily, you should keep your current key intact on your server as well as on your site's Pubcookie login server. To do so, use the keyclient's -d option when downloading the current key; otherwise the keyserver will generate a new one that isn't compatible with version 1.77.

Prerequisites

The module relies on additional infrastructure at your site. Here are some general prerequisites that, if fulfilled, will lead to a smooth, successful installation.

Note: one additional suggestion for more advanced uses. Review the sections on virtual host configuration or clustered host configuration now if either of those scenarios apply. The information will help you think about and tailor the simple case instructions while you go through them.

System Requirements

The module has the following system requirements:

Confirm SSL Support

Before you build and install the module, confirm that your SSL configuration is working and that Apache responds to HTTPS requests. The module requires a functioning SSL-enabled server.

If your Apache server does not already support SSL, refer to Appendix A: How to Enable SSL for guidelines.

Build & Install

The configure script included in the distribution helps you build and install the module according to your platform, Apache version, and individual preferences. It also helps you build and install the Pubcookie keyclient which will be used to obtain a symmetric encryption key for your server.

Step-by-step instructions follow below for building and installing these components on your server, including specific details for building the module as a Dynamic Shared Object (DSO) or statically compiling the module into Apache itself.

  1. Download the Pubcookie source code distribution.

  2. Unzip and untar the source files.

    $ gzip -d pubcookie-3.2.0.tar.gz
    $ tar xvf pubcookie-3.2.0.tar
    $ cd pubcookie-3.2.0

    Note: You can run the configure script and make the module (or new httpd binary) while logged in to a non-privileged user account, but you may want to be root to do the install.

  3. Decide if you want to build a DSO and load it dynamically using Apache's DSO support or statically compile the module into a new httpd binary.

    To build a DSO module:
    The default configure, make, make install process builds the DSO (mod_pubcookie.so) using apxs as found on your system. It also builds the keyclient and uses the default installation prefix, /usr/local/pubcookie, as the installation target directory.

    Use configuration options to customize as needed. For example:

    $ ./configure \
        --enable-apache \
        --prefix=/usr/local/pubcookie \
        --with-apxs=/path/to/apxs \
        --with-ssl=/path/to/openssl
    $ make
    $ make install

    Notes:

    To compile the module statically:
    The configure script can also prepare the source files to statically compile the module into Apache at build-time. Here the configure script uses the --with-apache-src option to copy the module's source files to your Apache source directory. It also creates a Makefile to build and install the keyclient. The process might look something like this:

    # add module src to Apache and generate Makefile for keyclient
    $ ./configure \
        --enable-apache \
        --prefix=/usr/local/pubcookie \
        --with-apache-src=/path/to/apache/src \
        --with-ssl=/path/to/openssl
    
    # build, install, setup keyclient
    $ make
    $ make install
    
    # configure, make, and install Apache
    $ cd /path/to/apache
    $ SSL_BASE=/usr/local/openssl ./configure \
        --prefix=/path/to/install/apache \
        --enable-module=ssl \
        --activate-module=src/modules/pubcookie/libpubcookie.a \
       [...more options...]
    $ make 
    $ make install

    Notes:

  4. Okay, you've reached a useful checkpoint. Lets pause to assess your progress.

    At this point you've either built a new DSO module or a new httpd binary. You've also built and installed the keyclient into the installation target directory. List this directory now to see that you have a keyclient binary and a new keys subdirectory:

    $ ls -F /usr/local/pubcookie
    keyclient*      keys/

    Note: Permissions. If you initially start Apache as root and use the User directive to switch to a non-root user, you can lock down your pubcookie directory permissions so that non-root users cannot read its contents.

Run Keyclient

Pubookie solves the problem of securely distributing symmetric encryption keys by introducing a keyserver. Participating servers make authenticated SSL/TLS connections to keyserver to obtain a host key. This section describes how to configure and run the Pubcookie keyclient utility to request keys from your local keyserver.

Tip: Ask your keyserver administrator for advice about configuring the keyclient. It's particularly important to know the Certificate Authority that signed (and therefore can verify) the keyserver's certificate.

To configure the keyclient:

  1. The keyclient accepts command-line options, but it's generally easier to configure by specifying values in a separate text configuration file. Go ahead and create one now:

    $ cd /usr/local/pubcookie
    $ pico config

    Note: keyclient uses a built-in location, based on your original installation prefix, to look for a config file and to store host keys. Adjust the path above accordingly.

  2. Add the following configuration variables and adjust their values according to your site:

    # ssl config
    ssl_key_file: /etc/httpd/conf/ssl.key/server.key
    ssl_cert_file: /etc/httpd/conf/ssl.crt/server.crt
    
    # keyclient-specific config
    keymgt_uri: https://weblogin.example.edu:2222
    ssl_ca_file: /etc/httpd/conf/ssl.crt/ca-bundle.crt 

    Notes:

  3. Save the changes to your config file.

To request a new symmetric encryption key:

  1. If necessary, ask your Pubcookie keyserver administrator to "permit" your server so that it can request a host key for itself. This requirement will depend on the local policy for server registration as well as the version of keyserver being used.

  2. Run keyclient to request a new key:

    $ ./keyclient
    Set crypt key for appserver.example.edu

    Notes:

    If keyclient fails for any other reason, note any error messages and refer to the Troubleshooting section below.

  3. List the contents of your keys directory to find the new key:

    $ ls /usr/local/pubcookie/keys
    appserver.example.edu

    Notes:

To download your site's Pubcookie "granting" certificate:

The module uses your Pubcookie login server's "granting" certificate to verify the digital signature of "granting" cookies sent from the login server to your server.

  1. Run keyclient with the -G option to retrieve your site's "granting" certificate.

    $ cd /usr/local/pubcookie
    $ ./keyclient -G keys/pubcookie_granting.cert
    Granting cert saved to keys/pubcookie_granting.cert

    Notes:

If keyclient cannot download your "granting" certificate, your keyserver may not support this retrieval method and you'll have to obtain a copy manually.

Configuration (httpd.conf)

Configuring the module begins with your main Apache server configuration httpd.conf file. This section describes what you need to add to this file.

  1. Edit your Apache server configuration file (httpd.conf), e.g.:

    $ pico httpd.conf

  2. (For DSO method only.) When working with the module as a DSO, the installation process uses apxs (Apache 1.3) or libtool (Apache 2.0) to install the module into Apache's modules (libexec) directory. Now the module needs a little configuration based on your version of Apache.

    Apache 1.3: LoadModule & AddModule
    With Apache 1.3, installation also adds new, but initially inactive, LoadModule and AddModule directives to your httpd.conf file. Find these directives. Make sure they landed in the right location. And uncomment them to activate them. For example:

    <IfDefine HAVE_SSL>
    LoadModule ssl_module         modules/libssl.so
    LoadModule pubcookie_module   modules/mod_pubcookie.so
    </IfDefine>
    
    ...
    
    <IfDefine HAVE_SSL>
    AddModule mod_ssl.c
    AddModule mod_pubcookie.c
    </IfDefine>

    Again, this is just an example. Your httpd.conf may differ.

    Warning: if your LoadModule and AddModule directives for the module are placed within an <IfDefine HAVE_SSL> block directive, all Pubcookie run-time directives must also be placed with an <IfDefine HAVE_SSL> block directive.

    Apache 2.0: LoadModule
    With Apache 2.0, add a LoadModule directive to your server config wherever it makes sense to do so. The AddModule directive no longer exists in Apache 2.0, so don't add one of those.

    LoadModule pubcookie_module   modules/mod_pubcookie.so

  3. Add a new section in httpd.conf for configuring the module:

    <IfDefine HAVE_SSL>
    <IfModule mod_pubcookie.c>
    
    #
    # Pubcookie configuration section
    #
    
    PubcookieGrantingCertFile /usr/local/pubcookie/keys/pubcookie_granting.cert
    PubcookieSessionKeyFile /etc/httpd/conf/ssl.key/appserver.key
    PubcookieSessionCertFile /etc/httpd/conf/ssl.crt/appserver.crt
    PubcookieKeyDir /usr/local/pubcookie/keys/
    
    PubcookieLogin https://weblogin.example.edu/
    PubcookieLoginMethod POST
    PubcookieDomain .example.edu
    PubcookieEncryption AES
    PubcookieAuthTypeNames EGNetID
    
    # Disable inactivity timeout by default
    <Directory "/var/www/html">
    PubcookieInactiveExpire -1
    </Directory>
    
    </IfModule>
    </IfDefine>

    Notes:

    To learn more about each directive, consult the module's run-time configuration directives reference.

  4. (Optional) Add other default settings as needed, such as default timeout durations. Refer to the module's run-time configuration directives reference for possibilities.

  5. (Optional) You may want to add logout configuration or better configuration for abbreviated domain names.

  6. (Optional) To enable the use of the module's per-application configuration directives within .htaccess files and <Directory> and <Location> block directives, adjust your server's AllowOverride setting to AuthConfig or All

  7. (Optional) The module uses the ServerAdmin address when reporting errors to users. Define an appropriate contact for problem reports.

  8. Save the changes to your httpd.conf file.

Start Apache

Okay, now things get exciting. If everything has gone smoothly so far, you should be able to start Apache. Give it a try, making sure to start your SSL-enabled server. For example:

$ /path/to/apache/bin/apachectl startssl

Notes:

Refer to the Troubleshooting section below for further help if Apache fails to start.

Test Pubcookie Authentication

  1. Create a new directory within your DocumentRoot. For example:

    $ cd /var/www/html
    $ mkdir testapp
    $ cd testapp

  2. In this directory, create a new Web page:

    $ pico index.html

    Add a simple message to the file such as "Hello pubcookie-protected world!" and save it.

  3. Create a .htaccess file:

    $ pico .htaccess

  4. Add the following directives to the .htaccess file:

    AuthType EGNetID
    require valid-user

    Substitute the appropriate argument for the AuthType directive, based on the authentication type defined with the PubcookieAuthTypeNames directive in httpd.conf. Note that using these directives in the .htaccess file context requires the AllowOverride AuthConfig setting.

  5. Start a Web browser and open the address for the test directory, e.g.:

    https://appserver.example.edu/testapp/

    You should be redirected to your Pubcookie login server.

  6. When you log in as requested, you will be redirected back to the test directory and you should see your "Hello world!" message. If you do, you have successfully installed and configured Pubcookie. Congratulations!

    Note: the module provides an authentication mechanism very similar to Apache's "basic" access control functionality. You can therefore expect some of the same results: namely, that the module sets the REMOTE_USER and AUTH_TYPE environmet variables, and also logs the userid in your access_log.

  7. Refer to the Troubleshooting section below if this test was unsuccessful.

Logout Configuration and Use

The PubcookieEndSession directive causes the module to clear the current session cookie. Therefore, it can be used to implement application logout.

Logout can be configured on a per-application basis using .htaccess or centrally using a virtual logout URI that any application on the server can use.

To configure logout using .htaccess:
The simplest way to configure logout for an application or static website is to place a .htaccess file in a subdirectory (e.g. logout) and put a PubcookieEndSession in the .htaccess file. It might be laid out something like this:

$ ls -a
.htaccess    images/    index.php    other.php    logout/
$ more .htaccess
PubcookieAppID testapp
Authtype EGNetID
require valid-user
$ more logout/.htaccess
PubcookieEndSession redirect

Then a link from any page to the subdirectory will steer users to logout, allowing PubcookieEndSession to do its work.

<a href="logout/">Logout</a>

To configure and use a matching logout URI:
This is a nice alternative for system administrators and application deployers who prefer not to use subdirectories and .htaccess files to configure logout. Essentially, by using Apache's LocationMatch directive you can create a server-wide matching string that causes the module to invoke PubcookieEndSession without the use of .htaccess. Simply by creating a link with the same string in it, an application can implement logout.

Here's example httpd.conf configuration which defines two such strings, LOGOUT-REDIRECT and LOGOUT-CLEARLOGIN, corresponding with two styles of application logout provided by Pubcookie.

<IfDefine HAVE_SSL>
<IfModule mod_pubcookie.c>

#
# Pubcookie configuration section
#

...

#
# Pubcookie logout configuration
#

<LocationMatch .*/LOGOUT-REDIRECT.*>
AuthType EGNetID
require valid-user
PubcookieEndSession redirect
</LocationMatch>

<LocationMatch .*/LOGOUT-CLEARLOGIN.*>
AuthType EGNetID
require valid-user
PubcookieEndSession clearLogin
</LocationMatch>

</IfModule mod_pubcookie.c>
</IfDefine>

With these directives in place, and the server restarted, any Pubcookie-protected application or static website on the server can create a logout function simply by linking to one of these virtual URIs. For example:

<a href="LOGOUT-REDIRECT">Logout</a>

Cross-Domain Relay Configuration

Authentication across DNS domains was greatly simplified in Pubcookie 3.2.0 with the addition of the POST-based PubcookieLoginMethod.

Virtual Host Configuration

One approach to configuring separate virtual hosts on the same system is to use your main server configuration section to establish default settings for Pubcookie, as described in the Configuration section above. Then override directives as needed for each virtual host.

For example, a separate session keypair should be used for each virtual host, which you can do by defining different PubcookieSessionKeyFile and PubcookieSessionCertFile directives within your virtual host configuration. It may be acceptable to use defaults for the module's other configuration settings.

To request a symmetric encryption key for each virtual server name, you can use your current config file to define default values and then override them using command-line options for each virtual host's SSL private key and certificate files. For example:

$ ./keyclient -k vhost.key -c vhost.crt
Set crypt key for vhost.example.edu

You can also set up a config file for each virtual host and use the keyclient's -f filename to point to each separately.

Clustered Host Configuration

System administrators frequently cluster together several hosts for better redundancy, performance, stability, and recoverability. Each host in the cluster is configured the same, so each has a SSL certificate and private key identical to the other cluster members.

For instance, a site might have 15 webmail servers named webmail1.example.edu through webmail15.example.edu with 15 unique IP addresses. As cluster peers, they're each equipped with the same SSL keypair for webmail.example.edu. A load-based DNS rotary or Cisco Load Director might control the IP address for the webmail.example.edu name itself.

To support such a cluster, use keyclient on one host, say webmail1.example.edu, to generate a webmail.example.edu host key. Then use keyclient -d on all other webmail hosts to download the existing host key to the remaining servers. This way, they all use the same key.

Wildcard Subdomain Key Configuration

Wildcard subdomain configuration allows the module to reuse a single host key file for protecting several server names in the same subdomain. For example, it allows a single students.example.edu host key to function as the encryption key for all the individual student web sites (abe.students.example.edu, bess.students.example.edu, spud.example.edu, etc.) as might happen on a large multi-user web-hosting environment.

It works like this: the actual key for AES encryption is a randomly chosen 128 bits from the host key file. To allow the same host key file to encrypt cookies for all subdomains the wildcard-subdomain encryption mode augments the usual 128 bits with the requested web site's full domain name. The key becomes SHA1( (128 bits from file) + (web site's full domain name) ). When the module fails to find a key for the requested web site's full domain name, it will look again with the first part of the name removed, i.e. for a key representing a wildcard for the subdomain.

This feature is enabled by setting the PubcookieEncryption directive to AES+DOMAIN and requires that Apache's UseCanonicalName directive is turned off.

Troubleshooting

To troubleshoot problems with keyclient, review the error messages it produces. If need be, ask your keyserver administrator to review syslog for keyserver error messages corresponding with your keyclient connections.

To troubleshoot problems with the module, first look in the Apache error_log. If need be you can log additional debug statements by setting the LogLevel to debug in your httpd.conf file.

Appendix A: How to Enable SSL

Note: This is just an overview; you'll have to look elsewhere for specific instructions if you need them. (The INSTALL file that comes with mod_ssl is particularly good.)

  1. Build and install OpenSSL.

  2. Build and install Apache from source and add SSL support by following the directions accompanying the mod_ssl package. You will have to decide whether to build modules dynamically or statically. If you use apxs (the Apache DSO module builder), be sure to link it with OpenSSL.

  3. Generate a RSA private key and certificate signing request (CSR) to obtain a signed SSL server certificate. Install the private key and server certificate as directed by the mod_ssl documentation.

    Note: You may end up reusing this keypair with the keyclient utility, in which case your certificate should be issued by a Certificate Authority trusted by your keyserver. And your private key should be readable without having to enter a passphrase to decrypt it.

  4. Verify that Apache responds to HTTPS requests. SSL should be working before you proceed to build and install the module.

Appendix B: Configuration For Abbreviated Domain Names

Because HTTP cookies must be scoped to a specific fully-qualified domain, the use of abbreviated domain names (e.g. "appserver" instead of "appserver.example.edu") affects the sending of cookies, which in turn affects, and causes problems for, Pubcookie.

To remedy this, you might use mod_rewrite to rewrite (and redirect) abbreviated domain names to fully-qualified domain names. Here is a sample configuration (for httpd.conf):

RewriteEngine on
RewriteCond %{HTTP_HOST} !^$
RewriteCond %{HTTP_HOST} !\.example\.edu
RewriteRule ^/(.*)$ https://%{SERVER_NAME}/$1 [L,R]

This rule is for a https requests only; you would need something similar for http requests. You may also need to add additional rules for subdomains (e.g. subdomain.example.edu). Additionally, abbreviated domain names must be in your ServerAlias list.