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
To support encrypted connections, you will need an SSL certificate. To generate a "junk" certificate for testing, you can use:
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:
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:
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:
Add the following information just before the line that reads ### Section 3: Virtual Hosts:
# Inactivity expire time, in seconds
# Hard expire time, in seconds
# File locations
# Application ID
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:
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 email@example.com.
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:
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 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:
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:
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