Installing Pubcookie: Windows

Prerequisites

Before you begin, you will need: SSL certificates, IIS Manager configured including HTTPS, and the Pubcookie MSI installer.

• SSL Certificates
  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

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.

• IIS configured, including HTTPS
• Pubcookie MSI installer
  To obtain the Carnegie Mellon Pubcookie MSI installer, visit http://www.pubcookie.org.

Install and Configure Pubcookie

1. Launch the InstallShield Wizard for Pubcookie. Click Next.
2. The License Agreement screen appears. Click the "I Accept" radio button then click Next.
3. The default configuration screen appears. In the "Application Server DNS Name" field, enter the fully qualified domain name of the server (e.g. acererak.cc.cmu.edu). Accept the other default values as they appear, then click Next.
   
   
4. The Custom Setup screen appears. Accept the default values and click Next.
5. The Ready to Install the program screen appears. Click Install.
6. Through the installation, the following messages may appear. Both are considered normal for the installation process:
   "Added Pubcookie Filter to root filter list. If you wish to add the filter to only specific web sites, use the Computer Management MMC snap-in to do so." Click OK.
   "Granting cert saved to C:\WINDOWS\system32\inetsrv\pubcookie\keys\pubcookie_granting.cert" . Click OK.
   
   Note: The following error message is NOT normal.
   
   
   
   This message indicates that the granting certificate failed to download properly. If you receive this message, click OK to continue with the installation. Once the installation is complete, send email to Advisor to obtain a copy of the granting certificate, then copy the granting certificate to c:\windows\system32\inetsrv\pubcookie\keys\pubcookie_granting.cert.
7. The following message appears, "Created and stored encryption key for [xxxxxx]" Click OK. (Where xxxxxx is the application server DNS name that you entered in step 3.)
8. The InstallShield Wizard Completed screen appears. Click Finish.

Cluster Key Installation

Note: The Cluster Key Installation may be necessary for dynamic web sites.

If the same server name is hosted on several machines, you have a clustered host configuration and will need to synchronize your installation and configuration among the cluster members. In particular, you need to make sure each member has a copy of the same host key and is using the same Pubcookie session key pair.

1. To synchronize the host key, when you run the installer on the first host, set the installer's keyclient behavior to obtain a new key. On subsequent hosts, set it to retrieve the old key. Another method is to obtain a new host key on the very last host and then copy it to the previous hosts.
2. To ensure each cluster member has the same session key pair, put the same key pair on each host, on disk, in the right location, and the filter will read it upon startup. The file names are System32\inetsrv\Pubcookie\keys\pubcookie_session.cert and System32\inetsrv\Pubcookie\keys\pubcookie_session.key, respectively.
   
   Note: any appropriately named key pair in PEM format will suffice for the session key pair. The difficulty on Windows is generating a key pair. If you can find a system that has OpenSSL, you can generate a new key pair with:
   
   $ openssl req -new -x509 -out pubcookie_session.cert \
   -newkey rsa:1024 -nodes -keyout pubcookie_session.key
   
   
3. As a result of this effort, each host will have the same contents in its Pubcookie keys folder.
   

Note: If you don't sychronize clustered hosts, session cookies set by one cluster member will not be readable by the other cluster members, resulting in Can't unbundle session cookie error messages in the Event log. 

Enabling PubCookie on a Directory

1. If you want to test the application, launch the Internet Information Services (IIS) Manager.
2. Select the Web Server Extension, then select Active Server Pages, then select Allow.
   
3. Click the Pubcookie Directives tab of a site's properties sheet.
   
4. From the Directive select box, choose AuthType. For Pubcookie authentication, choose NETID in the Value select box.
   
5. Select DES as your encryption type, not AES.
   
6. The following graphic depicts a working application. An example of an authorization is also included below.
   

   
   Authorization Example:
   
   <%
   user = Request.ServerVariables("HTTP_PUBCOOKIE_USER")

if (user = "eberhard@ANDREW.CMU.EDU") OR _ (user = "jalang@ANDREW.CMU.EDU")

then
…

else
…

endif
%>

<br clear="all">

Last Updated: 4/20/11