Included on this page:
This guide helps you install the Pubcookie ISAPI Filter on
Microsoft Internet Information Server. Objectives include:
- how to export your SSL certificate and private key using
the Certificate Export Wizard
- how to setup and use the Pubcookie keyclient to obtain
an encryption key
- how to add the Pubcookie ISAPI Filter to IIS
- how to test the Pubcookie ISAPI Filter to confirm that
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
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
- The SSL server certificate for your application server
must be signed by a Certificate Authority trusted by your
System requirements for your IIS machine are:
- Microsoft Windows NT 4.0 SP3 or later on Intel platform
- Microsoft Internet Information Server (IIS) 4.0 or 5.x
- SSL enabled Web site, using a 1024-bit private key
- Accurate system time
- A domain name (e.g. appserver.example.edu) registered
in DNS within same subdomain as your Pubcookie login server
Download and Unzip Win32 Distribution
Download the Pubcookie
ISAPI Filter distribution.
Unzip the distribution, extracting the files to:
This is the location assumed below. Among the files included
are: keyclient.exe, openssl.exe, pubcookiefilter.dll,
and some files to help with the installation process.
Verify SSL Private Key Size (1024
To begin, verify that your SSL key is 1024 bits:
Perhaps the simplest way to verify this is to open an
"https" connection to your website and ask your
browser to display the details of the certificate.
If your SSL key is not 1024 bits, you will need to replace
your current SSL certificate to work with Pubcookie. Generate
a new CSR (certificate signing request) based on a 1024-bit
private key (the default is 512 bits, so be sure to up
this to 1024) and have your Certificate Authority sign
a new certificate. Install the new certificate and then
Note: Pubcookie requires a 1024-bit private key!
Export and Convert
SSL Certificate and Private Key
To export your SSL cert and private key:
Bring up the IIS management console.
Select your web site, click Properties.
Select Directory Security tab.
Click View Certificate...
Select the Details tab, click Copy
- Follow the Certificate Export Wizard:
- click Next
- select Yes, export the private key;
- select PKCS #12 (.PFX);
check Enable strong protection;
- type and confirm password;
- enter a File name, e.g. C:\Temp\appserver.pfx;
- click Finish
- click Ok if the export was successful.
The intended result of all this is a PFX-formatted file appserver.pfx
containing your SSL certificate and private key.
To convert to PEM format from PFX:
Open a command prompt.
Run the following:
openssl pkcs12 -in appserver.pfx -out appserver.pem -nodes
This will produce appserver.pem right where you want
To separate your SSL certificate and private key:
Open appserver.pem in WordPad.
Use WordPad to extract the RSA private key into a new
file called pubcookie_session.key.
Use WordPad to extract the certificate into a second
new file called pubcookie_session.cert.
- Save both new files in C:\Temp where the rest of the
Setup Supporting Files and Registry
To assemble the remaining required files:
Get a copy of pubcookie_granting.cert
from your Pubcookie login server and place it in C:\Temp.
- Get a copy of the file containing your Certificate Authority's
certificate and place it in C:\Temp, e.g. C:\Temp\cacert.pem.
These instructions assume the use of a CA cert file, rather
than a directory, to establish the keyclient-keyserver trust.
Further work needs to be done to test and document setup
using a directory of possible CA certificates.
To install the supporting files in your Pubcookie
Edit PubcookieFilter_Install.bat in
C:\Temp to see what it does and to adjust any file names
if need be. Save it.
to run it. It will copy all the supporting files from
C:\Temp to a new Pubcookie folder in your System root
Remove Everyone access to this folder, then add SYSTEM
read and Administrator change control security settings.
- Make sure the PubcookieFilter.dll in
the Pubcookie folder is executable by SYSTEM accounts.
To prime the Windows registry with site-specific
Edit the example.reg in C:\Temp. Site-specific
changes should be made to several settings, which are
represented in example.reg by the following lines (extracted):
Refer to the Pubcookie ISAPI
Filter Windows Registry Settings document for further
explanation of these settings.
While you're editing example.reg, be sure to give the
"WebApp" application an AuthType setting so that it requires
authentication. example.reg comes with it already defined,
but you might want to fiddle with the values of the AuthTypeName1
string and corresponding AuthType string. Since AuthTypeName1
defines the string used as the AuthType value, they will
be the same (e.g. "FooID" above and in example.reg).
- Double-click example.reg to enter your settings into the
Request Encryption Key (Using Keyclient.exe)
To obtain an encryption key for your application
Open a command prompt.
Run the following:
keyclient -c pubcookie_session.cert -k pubcookie_session.key -C cacert.pem
Substitute file names appropriately. The keyclient looks
in the keys subfolder of your pubcookie directory for
If successful, keyclient will deposit a new DES key in
your Pubcookie folder, e.g.
If unsuccessful, look into your system event log for
an explanation why it failed.
Add PubcookieFilter.dll to Your Website
To add the Pubcookie ISAPI Filter to your default
website in IIS:
Start the Internet Service Manager (usually found
in your IIS program folder).
Right-click on the Web site into which you want to install
the Pubcookie ISAPI filter and select Properties
from the popup menu.
In the ISAPI Filters tab, click Add.
Enter Pubcookie for Filter Name.
Click Browse and locate the Pubcookie DLL for
Executable (e.g. %Systemroot%\System32\Inetsrv\Pubcookie\PubcookieFilter-3.0.0.dll).
Click Ok. And click OK
Right-click your Web site. Stop and restart it.
Verify that Pubcookie is installed by reviewing the Properties
of your Web site. The status of the Pubcookie ISAPI filter
should be loaded; the arrow should be up and green.
Test Pubcookie (with sample WebApp)
A sample application has been provided to test the ISAPI filter's
ability to authenticate against your configuration, to create a session,
and to terminate the session through Pubcookie's logout features. To
do the test:
Copy the sample WebApp folder from C:\Temp to your Web
site's root folder (e.g. C:\inetpub\wwwroot\WebApp).
You can think of this as creating a Pubcookie-protected
application called WebApp. The example.reg used earlier
assigns an AuthType setting to this application as well
as others for logout.
To test authentication, start a Web browser and open
/WebApp/ on your IIS server. For example:
You should be redirected to your Pubcookie login server.
After being authenticated, you should be redirected back.
Verify that the response generated by /WebApp/Default.asp
displays the correction information. In particular, the
Pubcookie User, as obtained thru the HTTP_PUBCOOKIE_USER
variable, should display your id. If so, Bob's your uncle
as far as authentication and seesion creation goes.
Now try to logout by selecting one of the logout links
provided by Default.asp. For example, click invoke
app-logout-and-redirect. This will make a request
Since this folder has been configured with a Logout_Action
registry setting by example.reg, it will clear your current
session cookie. In this case, the value assigned in the
registry also causes you to be redirected to your login
server, which, if all goes correctly, will serve a logout