Included on this page:

• Overview
• What's New
• 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
• Troubleshooting
• Appendix A: How to Enable SSL
• Appendix B: Configuration For Abbreviated Domain Names

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 :

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

• Added PubcookieNoObscureCookies directive to Apache module to replace broken PubcookieNoBlank directive.
• Added keyclient command-line option (-f <filename>) to specify alternate config file.
• Modified Apache module to assure that the configured enterprise domain starts with a dot.
• Bug fixes to preserve spaces during POST-based logins and to avoid a possible null pointer in REMOTE_REALM variable.

Significant improvements and changes included in Pubcookie 3.2.0:

• Added POST-based messaging between Apache module and login server. This method is compatible with 3.1 login servers and introduces two new directives: PubcookieLoginMethod and PubcookiePostURL. This feature obsoletes the 3.1 relay cgi.
• Added keyclient support for wild card certificates and Subject Alt Names (3.2.0 keyserver required).
• Cleaner request handling and improved compatibility with other Apache modules
• Exempted /favicon.ico location for browser compatibility issues
• Removed obsolete relay cgi component. See above.

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

Upgrading

Apache servers running version 3.0.0, 3.1.0, or 3.1.1 of the module should be easy to upgrade to the 3.2.0 release. Just build and install the new module and keyclient. You can reuse your existing configuration, granting certificate, and symmetric key.

Apache servers running earlier versions of the module (e.g. 1.77) may have to update their Apache configuration and will need to obtain a new symmetric key from their local keyserver.

Compatibility note on third-party relays: Use of third-part relays (i.e., those not on the same host as the application) is deprecated in version 3.2.0 and may not be supported by your site's deployment of the 3.2.0 login server. Application servers using the 3.1 relay cgi are strongly encouraged to upgrade to version 3.2.0 and use its POST-based messaging instead of the relay cgi.

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.

• 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, so that you 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 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:

   • 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 \ --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:

   • 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 secure SSL/TLS connections to keyserver to obtain a key. This section describes how to configure and run the Pubcookie keyclient utility to request a key 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 arguments, but it's generally easier to configure it via a separate text configuration file. Go ahead and create one now:

   $ cd /usr/local/pubcookie $ pico config

   Note: keyclient has a built-in idea, based on your original installation prefix, where to find its config file and store 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:

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

   • 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 appserver.example.edu

   Notes:

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

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 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> ... <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 PubcookieLogin https://weblogin.example.edu/ PubcookieDomain .example.edu PubcookieKeyDir /usr/local/pubcookie/keys/ PubcookieAuthTypeNames EGNetID # Disable inactivity timeout by default <Directory "/var/www/html"> PubcookieInactiveExpire -1 </Directory> </IfModule> </IfDefine>

   Notes:

   • These are the recommended server config directives. They're not all required to initialize the module. But it's a good exercise to configure them explicitly.

   • Add a PubcookieLoginMethod directive to control the messaging method (classic cookie-based or POST-based).

   • 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 added type corresponds with a "login flavor" offered by your login server. Most sites, however, 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 therefore Apache 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 lengths. 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:

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

   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

Cross-dns-domain scenarios have been greatly simplified in Pubcookie 3.2.0 with the addition of POST-based messaging. Just set PubcookieLoginMethod to POST to avoid the traditional cross-dns-domain constraits.

Note: the 3.1. relay cgi has been obsoleted by POST-based messaging. It is no longer supported in the distribution and its use is now deprecated.

Virtual Host Configuration

Virtual host support is new in Pubcookie 3.1. One approach to configuration is to use your main server config to set up defaults, as described in the Configuration section above. Then override directives as needed for each virtual host.

For example, you should use a separate session keypair for each virtual host, so you will need to define new PubcookieSessionKeyFile and PubcookieSessionCertFile directives for each. It may be acceptable to use defaults for all other module settings.

To request a symmetric encryption key for each virtual server, you can use your current config file and simply point keyclient to the 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

Clustered Host Configuration

System administrators frequently cluster together several hosts configured identically to provide redundancy (either for performance or stability). In this section, we're assuming that you have a set of machines with an identical SSL certificate and key on them.

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 DES key. Then use keyclient -d on all other webmail hosts to download the existing application key to the remaining servers. This way, they all use the same key.

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.