Carnegie Mellon University Website Home Page
 
Skip navigation and jump directly to page content
Accounts
Network, Phone & TV
Software
Email, Calendar, Mobile
Secure Your Computer
Clusters & Printing
Web Services
Web Login / WebISO
Pubcookie (WebISO)
About Pubcookie (WebISO)
Installing Pubcookie: Apache
Installing Pubcookie: Windows
Academic Technology Services
Technical Support & Services
Training & Education
Campus Partners
Information Security Office (ISO)
Media Technology Services

Installing Pubcookie: Apache

The following steps must be completed to install and use Pubcookie.

  • Set up Apache with SSL
  • Install and Configure Pubcookie
  • Generate and Install the Encryption Keys
  • Install the Granting Certificate

Set Up Apache with SSL

First, you need to set up and configure Apache with SSL encryption. On an Andrew workstation, software is installed by package. To tell package to install the Apache web server software, add the following to /etc/package.proto

%define doesapache
%define doesapachessl

To support encrypted connections, you will need an SSL certificate. To generate a "junk" certificate for testing, you can use:

/afs/andrew/data/db/kweb/mkcert.sh myserver.andrew.cmu.edu

Note: This junk certificate will not work with Pubcookie.

To obtain a certificate for a production web server, you'll either need to purchase one from a company like Thawte, Verisign, etc., or use the Carnegie Mellon Certificate Authority. To request a certificate using the CMU CA please visit the Certificate Authority web page.

After running the package and rebooting your machine, you should be able to connect to the Apache server on your machine by visiting http://"myserver".andrew.cmu.edu/ (where "myserver" is your server name). Also, you should be able to obtain an encrypted connection by visiting https://"myserver".andrew.cmu.edu (Note:"https" instead of "http"). You won't be able to continue until you can get an encrypted connection to your server.

Install and Configure Pubcookie

To install the Pubcookie software, add:

%define doespubcookie

to your /etc/package.proto file and run package. This will install the Pubcookie software, but it won't enable it.

To enable Pubcookie, you'll need to make some changes to your Apache configuration. To prevent package from overwriting your changes, you should also add:

%define hashttpd.conf
F /usr/www/conf/httpd.conf

Edit /usr/www/conf/httpd.conf and make the following additions. Assuming you are starting with the standard Andrew httpd.conf, just follow these instructions. If you are starting with a different httpd.conf, you may have to modify these instructions as appropriate.

In the section with the LoadModule lines, add:

LoadModule pubcookie_module libexec/mod_pubcookie.so

In the section with the AddModule lines, add:

AddModule mod_pubcookie.c

Add the following information just before the line that reads ### Section 3: Virtual Hosts:

<IfModule mod_pubcookie.c>
# Inactivity expire time, in seconds
PubCookieInactiveExpire 400
# Hard expire time, in seconds
PubCookieHardExpire 3700
# File locations
PubCookieGrantingCertFile /usr/www/pubcookie/keys/pubcookie_granting.cert
PubCookieSessionCertFile /usr/www/conf/ssl.crt/server.crt
PubCookieSessionKeyFile /usr/www/conf/ssl.key/server.key
PubCookieCryptKeyFile /usr/www/pubcookie/keys/host.name.cmu.edu
# Application ID
PubCookieAppSrvID appsrvid
PubCookieAppID appid
</IfModule>

Make the following changes:

  • Replace "appsrvid" with the name of your server (e.g., "www.andrew.cmu.edu").
  • Replace "appid" with a descriptive name for your application (e.g., "publishing").
  • Make sure the Session CertFile and KeyFile point to your SSL certificate and key file. Make sure the CryptKey points to the encryption key you will generate in the next step.

You'll also need to create a pubcookie-specific configuration file. Create a plain text file named /usr/www/pubcookie/config containing the following:

ssl_cert_file:/usr/www/conf/ssl.crt/server.crt
ssl_key_file:/usr/www/conf/ssl.key/server.key

Make sure that the values are the same as those you configured in httpd.conf for PubCookieSessionCertFile and PubCookieSessionKeyFile.

Generate and Install the Encryption Keys

The WebISO system uses strong encryption of all of the cookies that are used for authentication. In order for your web server to be able to decrypt cookies issued by the login server, you will need to have an encryption key file for your web server.

If you are using an SSL certificate issued by the Carnegie Mellon Certificate Authority, Verisign, Thawte, or InstantSSL, you can generate your own encryption key. To do this, you will need to run the keyclient program as follows:

/usr/www/pubcookie/bin/keyclient -c /usr/www/conf/ssl.crt/server.crt -k /usr/www/conf/ssl.key/server.key -D /usr/www/conf/ssl.crt/

Replace server.crt with the full pathname to your server certificate, server.key with the full pathname to your server certificate key file, and make sure that you have any appropriate intermediate certificates installed properly in the /usr/www/conf/ssl.crt/ directory.

If you are using an SSL certificate issued by any other certificate authority or a self-signed testing certificate, you will have to have Computing Services generate your key file for you by contacting webmaster@andrew.cmu.edu.

Install the Granting Certificate

In addition to encrypting the contents of all of the cookies, each cookie is also cryptographically signed. The pubcookie module verifies all cookies coming from the user to insure that the cookies haven't been modified. To verify cookies issued by the login server, pubcookie needs a copy of the granting certificate used by the login server. On an Andrew web server, this should be copied by package into /usr/www/pubcookie/keys/pubcookie_granting.cert. If you're not on an Andrew web server, you will have to copy the file from:

/afs/andrew.cmu.edu/data/db/pubcookie/client/usr/www/pubcookie/keys/pubcookie_granting.cert.

Protect Web Pages with Pubcookie

You can now use pubcookie to protect a directory on your web server. You can configure the protections either in your httpd.conf or in a .htaccess file in the directory you wish to protect.

To protect a directory in httpd.conf, use something similar to this:

<Directory /full/path/to/protect>
AuthType WebISO
PubCookieAppId appid
Require valid-user
</Directory>

or,

<Location /url/path/to/protect>
AuthType WebISO
PubCookieAppId appid
Require valid-user
</Location>

Directory takes a full path as its argument; Location takes a URL path.

To protect a directory with an .htaccess, just create the a file named .htaccess containing:

AuthType WebISO
PubCookieAppId appid
Require valid-user

The PubCookieAppId is optional; if you don't set it, it will be inherited from the httpd.conf. The Require directive tells Apache what user may access the resource. If you just use valid-user, any user who authenticates can access the resource. You can require specific users with:

AuthType WebISO
PubCookieAppId appid
Require user ju33@ANDREW.CMU.EDU
Require user bovik@CS.CMU.EDU

Any one of the users listed on a Require line will be allowed to access the resource. Currently, the login server will allow users to authenticate using accounts from ANDREW.CMU.EDU, QATAR.CMU.EDU, CS.CMU.EDU, or ECE.CMU.EDU.

If you are protecting a CGI directory, you can access the user's ID through the REMOTE_USER environment variable.

Last Updated: 8/24/12