Apache Module Installation Guide
Included on this page:

  • Overview
  • What’s New
  • Compatibility Notes
  • Upgrading
  • Prerequisites
  • System Requirements
  • Confirm SSL Support
  • Build & Install
  • Run Keyclient
  • Configuration (httpd.conf)
  • Start Apache
  • Test Pubcookie Authentication
  • Logout Configuration
  • Cross-Domain Relay Configuration
  • Virtual Host Configuration
  • Clustered Host Configuration
  • Wildcard Subdomain Key Configuration
  • Troubleshooting
  • Appendix A: How to Enable SSL
  • Appendix B: Configuration For Abbreviated Domain Names


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 :

  • Build and install the module for use with either Apache 1.3 or 2.0;
  • Use the Pubcookie keyclient to obtain a symmetric encryption key from your local Pubcookie keyserver and retrieve your site’s Pubcookie “granting” certificate;
  • Configure the module by adding directives to Apache’s httpd.conf;
  • Start Apache and test the module to confirm that authentication is working.

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

  • Fix handling of angle brackets in the argument names in POST data.

Significant improvements and changes included in Pubcookie 3.3.3:

  • Fixed handling of requests to /favicon.ico when Pubcookie authentication isn’t enabled.
  • Fixed internal redirects to forward mod_pubcookie headers to the new request record.
  • Fixed POST login method to preserve and restore query string as well as post data.
  • Added some type casts to avoid compiler warnings.

Significant improvements and changes included in Pubcookie 3.3.2d:

  • Fixed bug in verify_url function causing some characters such as colons to be converted to other chars during login.

Significant improvements and changes included in Pubcookie 3.3.2c:

  • Fixed bug in use of output filters introduced in version 3.3.2, in Apache 2.0.49 and higher, whereby headers set in the ‘filter’ mode are dropped when the module creates response content, logouts, errors, etc.

Significant improvements and changes included in Pubcookie 3.3.2b:

  • Modified Apache module to handle ‘+’ chars in base-64-encoded path. This fixes possible truncations of uri’s sent through the login process.

Significant improvements and changes included in Pubcookie 3.3.2a:

  • Modified Apache module to verify that the login server sends a non-empty userid in the granting reply, unless PubcookieNoPrompt is on.
  • Modifed Apache module to url-encode ‘+’ chars after base64-encoding query strings. This fixes possible truncations of uri’s sent through the login process.
  • Fixed out of place “char *datestr” declaration.

Significant improvements and changes included in Pubcookie 3.3.2:

  • Improved Apache 2.x compatibility. For Apache 2.0.49 and above, the module sets output headers in an output filter. This provides better interoperability with other modules too, in particular, mod_proxy_ajp.
  • Added PubcookieNoCleanCreds directive to allows an application to handle flavor_getcred credential cleanup.

Significant improvements and changes included in Pubcookie 3.3.1:

  • Added PubcookieCatenateAppIDs directive
  • Improved Makefile for Apache 2.2 builds.
  • Modified session reauthentication messaging. The module now verifies that the login cgi handled a reauthentication request when session reauthentication is configured. (Requires 3.3.1 or higher login server.)
  • Fixed bug in AES encryption mode that causes session cookies to be unreadable when PubcookieInactiveExpire is on.
  • Modified the module’s startup process such that it halts if security initialization fails (e.g., PubcookieSessionCertFile doesn’t exist).

Significant improvements and changes included in Pubcookie 3.3.0a:

  • Fixed encryption problems found with some virtual host configurations.
  • Modified POST PubcookieLoginMethod to use HTTP 302 redirects instead of meta-refresh on redirect back to the resource.
  • Updated the module’s handling of output values when printing redirect pages.

Significant improvements and changes included in Pubcookie 3.3.0:

  • Added AES encryption as the default encryption algorithm requested by and used by the module. To interoperate with earlier versions of the login server, set PubcookieEncryption to DES or build the module with the --enable-default-des configure option.
  • Removed pre-session cookie countermeasure when using POST PubcookieLoginMethod. It’s unneeded complexity and in this case an unnecessary countermeasure.
  • Added wildcard subdomain key capability for large multi-user web-hosting environments.
  • Better handling of stray, malicious, and other spurious cookies. The module will read all available session, pre-session, and granting cookies, until it finds a valid one. Previously it only checked the first one, which may be invalid.

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.


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.


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

  • Determine the location of your site’s Pubcookie login server. You’ll need this URL to configure the module. You may also want to find out its version, for compatibility reasons, and to know what features it supports.
  • Determine the location of your site’s Pubcookie keyserver. You’ll need this URL to request a symmetric encryption key that your server will share with your login server. Depending on the keyserver version and site policy, you may also need to ask your administrator to “permit” your server to request keys.
  • Determine how trust is handled by your site’s Pubcookie keyserver. You’ll need to know which Certificate Authorities the keyserver trusts to verify certificates. Similarly, you’ll need to know which Certificate Authority can verify the keyserver’s certificate. Ask your administrator for guidelines; it’ll save you time and effort.
  • Determine how your site distributes its Pubcookie “granting” certificate. You’ll need a copy of this certificate to verify the “granting” cookies signed and sent by your site’s login server. You may be able to download it from your keyserver, or you may have to obtain it manually. Ask your administrator which method to use.

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:

  • Unix platform.
  • Accurate system time.
  • OpenSSL library.
  • Apache HTTP Server. Versions 1.3 and 2.0.49 and above are supported.
  • SSL enabled web server. The mod_ssl package is recommended. See our FAQ for information about using Apache-SSL.
  • SSL keypair. An SSL server certificate and private key.Note: Pubcookie uses elements of public-key infrastructure (PKI) for server authentication and data privacy. Therefore, as you might expect, your SSL server certificate and private key can play a role here. However, a self-signed certificate may not pass muster.
  • Domain name registered in DNS (e.g. appserver.example.edu) .Note: If your server doesn’t share a common DNS subdomain (e.g. .example.edu) with your site’s Pubcookie login server (e.g. weblogin.example.edu) or if your enterprise DNS domain is in a country code top-level domain (e.g. example.ca) then you should use POST-based messaging configured by the PubcookieLoginMethod.

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 configuremakemake 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 
    $ make
    $ make install


    • The --prefix option defines the installation prefix where supporting files are installed and found.
    • The configure script will detect your version of Apache (1.3 vs 2.0) based on apxs as found on your system. Use --with-apxs when you have more than one copy or version of Apache installed on your system.
    • Use the --with-ssl option when you have more than one version of OpenSSL installed on your system.
    • Running make install uses apxs (Apache 1.3) or libtool (Apache 2.0) to copy the DSO to Apache’s modules (libexec) directory. With Apache 1.3, it also adds inactive LoadModule and AddModule directives to your httpd.conf file.

    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 
    # build, install, setup keyclient
    $ make
    $ make install
    # configure, make, and install Apache
    $ cd /path/to/apache
    $ SSL_BASE=/usr/local/openssl ./configure 
       [...more options...]
    $ make 
    $ make install


    • You still run make and make install while in the pubcookie directory because you need to build and install the keyclient. No worries, it won’t build the module or Apache.
  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


    • To negotiate the SSL/TLS connection to your keyserver, the SSL certificate used by the keyclient (i.e., ssl_cert_file) must be signed by a Certificate Authority trusted by your site’s keyserver.
    • Likewise, the certificate presented by the keyserver must be signed by a CA trusted by your keyclient; that is, it will be verified using the CA root certificates define by ssl_ca_file or ssl_ca_path. Ask your site administrator what CA root certificate should be used to verify your keyserver certificate.
  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


    • Use the keyclient’s -f <filename> option (requires version 3.2.1 or higher) to specify an alternate config file.
    • The keyclient uses the installation prefix by default to determine the path to your keys directory. You can override this using the keydir config file variable.
    • The key’s filename is derived from your certificate’s Common Name field.
    • If you use a wild card certificate (e.g., the CN is *.subdomain.example.edu), use the -H <hostname> keyclient option to specify your actual server name (e.g., -H host.subdomain.example.edu).
    • Likewise, if your server name is one of several names in your certificate’s Subject Alt Name field, use the -H <hostname> keyclient option to specify the server name that should be used for the key request.
    • If keyclient says “NO you (appserver.example.edu) are not authorized for keys“, contact your local site administrator to learn how to register your application server.

    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


    • The key’s filename is derived from your certificate’s Common Name field which should match the domain name visitor’s see in the URL for your website.
    • During configuration, this key is found within the directory defined by the PubcookieKeyDir directive or corresponds directly with the PubcookieCryptKeyFile directive.
    • Each key works fine with either encryption method offered by the PubcookieEncryption directive.

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


    • If you use a wild card certificate or a Subject Alt Name, use the same -H option used to request your encryption key.
    • During configuration, this certificate corresponds with the PubcookieGrantingCertFile directive in httpd.conf.

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 HAVE_SSL>
    AddModule mod_ssl.c
    AddModule mod_pubcookie.c

    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


    • These are recommended configuration directives, but they’re not all required to initialize the module. It’s a good exercise, however, to configure them explicitly, so you know what’s going on.
    • PubcookieEncryption defines the encryption algorithm used by the module. Since the module chooses the algorithm that the login server will use to encrypt messages, it’s important to get this one correct. (See compatibility notes.)
    • PubcookieLoginMethod defines the messaging method used by the module. Servers in country code top-level domains (e.g. .ca.de) must use the POST method.
    • PubcookieDomain is unnecessary if you use POST as your PubcookieLoginMethod.
    • PubcookieAuthTypeNames defines the authentication types that the module enables as additional arguments to the AuthType directive. (EGNetID just happens to be what they use at Example State University.) Each type you define should correspond with a “login flavor” offered by your login server. Most sites have just one.
    • Turning off the inactivity expiration via the PubcookieInactiveExpire directive provides a modest performance boost, since session cookies aren’t signed as often when there is no inactivity timeout. Applications that require an inactivity timeout can always override the default setting.
    • Warning: If your LoadModule and AddModule directives reside within an <IfDefine HAVE_SSL> block directive then all the module’s configuration directives must also reside within an <IfDefine HAVE_SSL>block directive. This is the convention used throughout this guide.
    • Permissions. If you initially start Apache as root and use the User directive to switch to a non-root user, the module’s supporting files can be made readable only by root. If you start Apache as a non-root user, then that user must be able to read the supporting file.
    • The RSA private key represented by PubcookieSessionKeyFile cannot be encrypted. The module won’t initialize, and Apache therefore won’t start, if this key requires a passphrase.

    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


  • If you use Apache’s apachectl script to start Apache, you might run apachectl configtest to do a configuration file syntax test before starting Apache. Often this catches simple mistakes and typos.
  • If Apache fails to start, don’t panic. Diagnostic messages may be sent to the console or more likely to your Apache error_log file. Before you ask someone for help, review the error messages for hints about what went wrong.
  • If Apache fails to start and your error_log says “security_init: couldn't parse session key“, then your RSA private key represented by PubcookieSessionKeyFile is probably encrypted. The module won’t initialize and therefore Apache won’t start if this key requires a passphrase.

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

    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 .*/LOGOUT-CLEARLOGIN.*>
AuthType EGNetID
require valid-user
PubcookieEndSession clearLogin

</IfModule mod_pubcookie.c>

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.edubess.students.example.eduspud.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.


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.