Included on this page:

• Objectives
• What's New
• Upgrading
• Prerequisites
• System Requirements
• Build Pubcookie
• Install Pubcookie
• Install Granting Certificate
• Configure Pubcookie Config File (config)
• Request an Encryption Key (using keyclient)
• Configure & Start Apache (httpd.conf)
• Logout Configuration and Use
• Test Pubcookie (with sample .htaccess)
• Debugging

Objectives

This guide helps you install mod_pubcookie on Apache 1.3.x. Objectives include:

• how to build and install mod_pubcookie 3.0.0 on Apache 1.3.x
• how to use the Pubcookie keyclient to obtain an encryption key
• how to configure Apache as a Pubcookie application server
• how to test mod_pubcookie to confirm that authentication works

What's New

Significant changes since mod_pubcookie-3.0.0-rc1:

• All per-application configuration directives are now enabled via AllowOverride AuthConfig in httpd.conf. Thus, the legal context for some directives has changed and may require require minor adjustments. Refer to the Configure Apache section for details.

Significant changes since mod_pubcookie-3.0.0-beta3:

• mod_pubcookie is now configured by Apache config files and server directives only. See Configure Apache. The keyclient command-line utility continues to use the Pubcookie config file for its configuration.

Significant changes in Pubcookie 3.0 in general:

• Each application server is assigned a unique DES key based on the server name identified by its SSL server certificate. This key is obtained using a Pubcookie keyclient utility. The keyclient cannot retrieve a key unless the application server's SSL server certificate is signed by a Certificate Authority known to the keyserver that issues and manages these keys for the Pubcookie login server.

• A new Pubcookie-specific run-time configuration file is now supported. On application servers it is used to configure the keyclient utility.

• In pre-3.0 versions of this guide, a separate key pair was generated for signing session cookies. This guide now shows how to reuse a server's existing SSL key pair for this purpose.

Upgrading

Upgrading from mod_pubcookie-3.0.0-rc1 or 3.0.0-beta3:

• If you define PubcookieInactiveExpire in httpd.conf, make sure it is defined within a <Directory> or <Location> block directive. Refer to the Configure Apache section for an example.

• If you are upgrading from mod_pubcookie-3.0.0-beta3, you will need to reconfigure mod_pubcookie using Apache config files and server directives. Refer to the Configure Apache section for details.

• The Pubcookie config file is no longer used to configure the module; only the keyclient uses the Pubcookie config file.

• Your existing DES key (retrieved by keyclient) should work; although you may want to test the new keyclient and retrieve a new one.

Upgrading from pre-3.0 versions of mod_pubcookie:

• Apache application servers being upgraded from versions of mod_pubcookie previous to 3.0 (and 3.0 betas) must obtain a new DES key using the new keyclient utility. (See What's New above and Using Keyclient below). To reuse your existing DES key, backwards compatibility arrangements must be made on your login server. Check with your login server administrator for that possibility.

Prerequisites

It is assumed that someone has already deployed a Pubcookie 3.0 login server and keyserver:

• If you deployed your own Pubcookie login server, locate your granting certificate (e.g pubcookie_granting.cert). It is one of the supporting files you'll need for your application server.

• If you didn't deploy your Pubcookie login server (e.g. weblogin.example.edu), contact the people at your institution who did . They will have information about obtaining your login server's granting certificate and may have further advice for setting up your application server.

• The SSL server certificate used by the Pubcookie keyclient utility, which is often the same server certificate used for SSL, must be signed by a Certificate Authority trusted by your site's Pubcookie keyserver.

System Requirements

System requirements for your Apache server include:

• Unix platform
• Accurate system time
• A domain name (e.g. appserver.example.edu) registered in DNS within the same subdomain as your Pubcookie login server (e.g. weblogin.example.edu).
• A working Apache server (version 1.3.x) with:
  • mod_ssl or Apache-SSL patches
  • SSL server certificate
• OpenSSL

Build Pubcookie

mod_pubcookie can be built as a Dynamic Shared Object (DSO) or it can be built into Apache itself (statically linked). Before you build mod_pubcookie, install and test Apache with SSL support, which is required.

General guidelines for adding SSL support to Apache:

If your Apache server does not already support SSL, here are some guidelines for adding it. Note: this is just an overview; you'll have to look elsewhere for specific instructions if you need them.

1. Build and install OpenSSL.

2. Build and install Apache from source with SSL support by following the directions accompanying the mod_ssl or Apache-SSL source. This is when you will decide 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 private key and CSR (certificate signing request) to obtain a signed SSL server certificate and install the private key and server certificate as directed by the mod_ssl or Apache-SSL documentation. (Note: You will probably reuse this keypair with Pubcookie's keyclient utility, in which case your cert should be signed by a Certificate Authority trusted by your Pubcookie keyserver. Contact your Pubcookie login server administrator for recommended certificate issuers.)

4. Verify that Apache with SSL support works before you proceed to build and install mod_pubcookie.

To build mod_pubcookie as a DSO using apxs:

1. Download the Pubcookie distribution.

2. Untar a copy of the source, e.g.:

   zcat (download_dir)/pubcookie-3.0.0.tar.gz | tar xf -

3. Run the autoconf configure script.

   % ./configure

   By default, it creates a Makefile that builds mod_pubcookie.so and the keyclient utility.

4. Do a make:

   % make

   This will build the DSO module and a keyclient binary.

To build mod_pubcookie as a built-in (statically linked) module:

1. Download the mod_pubcookie distribution.

2. Untar a copy of the Pubcookie source code, placing it where you would put other modules, e.g.:

   % cd /usr/local/src/apache_1.3.xx/src/modules % zcat (download_dir)/pubcookie-3.0.0.tar.gz | tar xf -

3. If you use the top level Apache Configure script, you will need to add the following option to configure it:

   --activate-module=src/modules/pubcookie-3.0.0/src/mod_pubcookie.a

   Or, if you use a src level Configure script, add an AddModule directive for pubcookie to the Configuration file and run the Configure script.

4. After running the configure scripts, do your 'make' to build a new Apache daemon with mod_pubcookie now statically linked in.

5. Install your new Apache daemon. But complete these installation and configuration instructions before starting it.

6. One more thing: build the keyclient utility too, e.g.:

   % cd pubcookie-3.0.0 % ./configure % make keyclient

Install Pubcookie

In this section, you will install Pubcookie by using, or mimicing, the Makefile generated by the configure script.

1. You can use the Makefile to install Pubcookie:

   % make install

   Note: If you want to install manually, it's covered in the next step. Running make install will create your Pubcookie directory, i.e. where Pubcookie stores its supporting files (config file, keys, certs, etc.) The default location is /usr/local/pubcookie, as defined in the configure script. It will also activate mod_pubcookie by copying the DSO module to the appropirate location and by modifying your httpd.conf file. You may want to check that the LoadModule and AddModule directives landed in the right section of your httpd.conf.

2. If you prefer to do this work manually, here's what you need to do to catch up:

   1. Create your Pubcookie directory and its keys subdirectory:

      % mkdir /usr/local/pubcookie % mkdir /usr/local/pubcookie/keys

      Non-privileged accounts should not be able to access files in your Pubcookie directory.

   2. Copy the module to your module library directory. For example:

      % cp mod_pubcookie.so /etc/httpd/modules

   3. Edit your Apache server configuration file (httpd.conf), adding new LoadModule and AddModule directives to the appropriate sections. 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 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.

Install Granting Certificate

1. Obtain a copy of your Pubcookie login server's granting certificate and put it in the keys subdirectory of your Pubcookie directory, e.g.:

   % cp pubcookie_granting.cert /usr/local/pubcookie/keys

   This certificate is created as part of deploying the Pubcookie login server. It holds the login server's public key, which is required in order to verify the signature of the granting cookies sent from the login server to your application server.

   Note: During configuration, this certificate corresponds with the PubcookieGrantingCertFile directive in httpd.conf. It also corresponds with the granting_cert_file config file variable, which is only necessary if you choose a filename other than pubcookie_granting.cert.

Configure Pubcookie Config File (config)

The Pubcookie keyclient utility uses a run-time configuration file. In this section you will create your Pubcookie config file and add all the necessary configuration variables required by the keyclient utility.

1. Create and edit your Pubcookie config file:

% pico /usr/local/pubcookie/config

2. Add the following lines to the config file and adjust the 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

Note: The Pubcookie config file reference describes these configuration variables, but you may have to contact the people who deployed your Pubcookie login server and keyserver for the correct site-specific values.

3. Save the changes to your new Pubcookie config file.

Request an Encryption Key (using keyclient)

Pubookie 3.0 uses a pair of utilities, called keyclient and keyserver, to negotiate and distribute DES encryption keys to application servers. (The keys are used to encrypt and decrypt the authentication assertions sent by the login server in the from of Pubcookie's "granting" cookies.)

In this section you will use the keyclient utility to request and install a new encryption key for your application server.

1. Run the keyclient utility to request a new DES key:

   % keyclient

2. If successful, keyclient will store the new keyfile in the keys subdirectory in a file named after your server, e.g.:

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

3. If keyclient is not successful retrieving a key, note any error messages and refer to the Debugging section below.

Configure & Start Apache (httpd.conf)

The Pubcookie module is initially configured by directives in the Apache config files. In this section you will add the necessary directives to your httpd.conf file.

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

   % pico httpd.conf

2. Define a new section for mod_pubcookie run-time configuration directives.

   <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 in DocumentRoot # <Directory "/var/www/html"> PubcookieInactiveExpire -1 </Directory> </IfModule> </IfDefine>

   It is recommended that you define each of these directives even though they are not all required in order to start Apache.

   Note: The PubcookieAuthTypeNames directive defines the strings that mod_pubcookie enables as additional arguments to the AuthType directive.

   Note: Turning off the inactivity expiration via the PubcookieInactiveExpire directive provides a modest performance boost, since session cookies don't have to be signed so often. Applications that require an inactivity timeout can always override this default setting.

   Warning: if your LoadModule and AddModule directives 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. This, of course, is how it is done throughout this installation guide.

3. Take this opportunity also to add any other system-wide configuration you want for your Pubcookie application server, such as default timeout lengths. See the mod_pubcookie run-time configuration directives reference for the various possibilities.

4. Now enable the use of mod_pubcookie's application-specific configuration directives inside .htaccess files and <Directory> and <Location> block directives. To do so, set your server's AllowOverride setting to AuthConfig:

   AllowOverride AuthConfig

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

6. Start or restart your server.

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

Logout Configuration and Use

The PubcookieEndSession directive causes mod_pubcookie to clear the current session cookie. Therefore, it is used to implement application logout. This directive can be configured on a per-application basis using .htaccess or configured centrally to create a virtual logout URI that any application on the server can link to in order to implement its own logout function without the need for .htaccess.

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 sysadmins 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 mod_pubcookie 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 this in place, and the server restarted, any Pubcookie-protected application or static website on the server can now implement logout simply by linking to one of these virtual URIs. For example:

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

Test Pubcookie (with sample .htaccess)

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 world - I'm Pubcookie-protected!!" and then 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 string you defined with the PubcookieAuthTypeNames directive in your httpd.conf (see above). Note that using these directives in the .htaccess file context requires the AllowOverride AuthConfig setting (also mentioned above).

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!

7. If this test is unsuccessful, refer to the Debugging section below.

Debugging

To debug problems with the keyclient utility, look in your syslog log files. If need be, add the following variables to your Pubcookie config file to increase the amount of reporting and re-run keyclient:

debug: 9
logging_level: 20

To debug problems with mod_pubcookie, look in your Apache server's error_log. If need be, edit your Apache httpd.conf file and turn on the debug mode (requires server restart) to get additional information:

LogLevel: debug