Included on this page:
This guide helps you install the Pubcookie application server software on Apache. Objectives include:
Note: The most recent version of this guide is always available online. See install-mod_pubcookie-3.0.html.
Pubcookie 3.0 changes that affect the use of mod_pubcookie:
Each application server is now assigned a unique DES key based on the server name identified by its SSL server certificate. This key is obtained using a new Pubcookie keyclient utility. The keyclient cannot retrieve a key unless the application'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. It is used to configure the keyclient utility as well as many aspects of mod_pubcookie previously configured via directives put in httpd.conf.
Apache application servers being upgraded from previous versions of mod_pubcookie 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.
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.
System requirements for your Apache server:
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.
Build and install OpenSSL.
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.
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: Pubcookie's key distribution model requires that your SSL server certificate is signed by a Certificate Authority trusted by your Pubcookie key server.)
Verify that Apache with SSL support works before you
proceed to
build mod_pubcookie.
To build mod_pubcookie as a DSO using apxs:
Download the Pubcookie 3.0.0-beta3 distribution.
Untar a copy of the source, e.g.:
zcat (download_dir)/pubcookie-3.0.0-beta3.tar.gz | tar xf - |
Run the autoconf configure script.
% ./configure |
By default, it creates a Makefile that builds mod_pubcookie.so and the keyclient utility.
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:
Download the mod_pubcookie distribution.
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 |
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-beta3/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.
After running the configure scripts, do a 'make' to create a new Apache daemon with mod_pubcookie now statically linked in.
In this section, you will install Pubcookie by using, or mimicing, the Makefile generated by the configure script.
If you built Pubcookie as a DSO module, you can use the Makefile to install Pubcookie:
% make install |
Note: This will create your Pubcookie directory - 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 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.
If you prefer to do this work manually, here's what you need to do to catch up:
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.
Copy the module to your module library directory. For example:
% cp mod_pubcookie.so /etc/httpd/modules |
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.
Note: 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.
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. During configuration, this certificate corresponds with the granting_cert_file config variable.
The Pubcookie module and keyclient make use of a configuration file. In this section you will create your Pubcookie config file, adding to it all the necessary run-time configuration variables.
Create and edit your Pubcookie config file:
% pico /usr/local/pubcookie/config |
# 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 # other site-specific config granting_cert_file: /usr/local/pubcookie/keys/pubcookie_granting.cert login_uri: https://weblogin.example.edu login_host: weblogin.example.edu enterprise_domain: .example.edu |
The Pubcookie config file reference has descriptions of these configuration variables, but you may have to request some of this information from the people who deployed your Pubcookie login server and keyserver.
Save the changes to your new Pubcookie config file.
Pubookie 3.0 uses a pair of utilities, called keyclient and keyserver, to negotiate and distribute the DES keys used to encrypt and decrypt information sent in granting cookies. In this section you will use the keyclient utility to request and install a new encryption key for your application server.
Run the keyclient utility to request a new DES key:
% keyclient |
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 |
If keyclient is not successful retrieving a key, note any error messages and refer to the Debugging section below.
The Pubcookie modules requires additional configuration, above what it receives thru your Pubcookie config file. In this section you will add the necessary directives to your httpd.conf file.
Edit your Apache server configuration file (httpd.conf), e.g.:
% pico httpd.conf |
Add a new section for Pubcoookie run-time directives. The PubcookieAuthTypeNames directive is required. You might also turn off the inactivity timeout, e.g.:
<IfDefine HAVE_SSL> # Pubcookie Configuration PubcookieAuthTypeNames EGNetID PubcookieInactiveExpire -1 </IfDefine> |
The PubcookieAuthTypeNames directive defines the strings that mod_pubcookie enables as additional arguments to the AuthType directive.
Note: 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.
Take this opportunity also to add any other system-wide configuration you want for your Pubcookie application server, such as default timeout lengths. See run-time configuration directives reference for the various possibilities.
It is likely that you will want to permit the use of Pubcookie via .htaccess files. To do so, you may need to adjust your server's AllowOverride setting, e.g.:
AllowOverride AuthConfig |
Note: some run-time directives, such as PubcookieAppID, require that this be set to "All".
Save the changes to your httpd.conf file.
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.
To test the Pubcookie Apache module:
Create a new directory within your DocumentRoot. For example:
% cd /var/www/html % mkdir testapp % cd testapp |
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.
Create a .htaccess file:
pico .htaccess |
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 AuthTypeNames directive in your httpd.conf (see above). Note that using these directives in a .htaccess file requires the AllowOverride AuthConfig configuration (also mentioned above).
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.
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!
If this test is unsuccessful, refer to the Debugging section below.
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 |