LATEST ARTICLES

ISAPI Filter Installation Guide

0
install ISAPI extensions

Objectives

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 authentication works

Prerequisites

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.
  • The SSL server certificate for your application server must be signed by a Certificate Authority trusted by your Pubcookie keyserver.
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 (e.g. weblogin.example.edu)

Download and Unzip Win32 Distribution

  1. Download the Pubcookie ISAPI Filter distribution.
  2. Unzip the distribution, extracting the files to:
    C:Temp
    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 bits required)

To begin, verify that your SSL key is 1024 bits:
  1. 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.
  2. 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 continue.
Note: Pubcookie requires a 1024-bit private key! ISAPI-Filter ISAPI Filter Installation Guide

Export and Convert SSL Certificate and Private Key

To export your SSL cert and private key:
  1. Bring up the IIS management console.
  2. Select your web site, click Properties.
  3. Select Directory Security tab.
  4. Click View Certificate
  5. Select the Details tab, click Copy to File
  6. Follow the Certificate Export Wizard:
    1. click Next
    2. select Yes, export the private key; click Next
    3. select PKCS #12 (.PFX); check Enable strong protection; click Next
    4. type and confirm password; click Next
    5. enter a File name, e.g. C:Tempappserver.pfx; click Next
    6. click Finish
    7. 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:
  1. Open a command prompt.
  2. Run the following:
    cd C:Temp
    openssl pkcs12 -in appserver.pfx -out appserver.pem -nodes
    This will produce appserver.pem right where you want it.
To separate your SSL certificate and private key:
  1. Open appserver.pem in WordPad.
  2. Use WordPad to extract the RSA private key into a new file called pubcookie_session.key.
  3. Use WordPad to extract the certificate into a second new file called pubcookie_session.cert.
  4. Save both new files in C:Temp where the rest of the files reside.

Setup Supporting Files and Registry Settings

To assemble the remaining required files:
  1. Get a copy of pubcookie_granting.cert from your Pubcookie login server and place it in C:Temp.
  2. Get a copy of the file containing your Certificate Authority’s certificate and place it in C:Temp, e.g. C:Tempcacert.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 directory:
  1. Edit PubcookieFilter_Install.bat in C:Temp to see what it does and to adjust any file names if need be. Save it.
  2. Double-click PubcookieFilter_Install.bat to run it. It will copy all the supporting files from C:Temp to a new Pubcookie folder in your System root called:
    %Systemroot%System32InetsrvPubcookie
  3. Remove Everyone access to this folder, then add SYSTEM read and Administrator change control security settings.
  4. Make sure the PubcookieFilter.dll in the Pubcookie folder is executable by SYSTEM accounts.
To prime the Windows registry with site-specific settings:
  1. 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):
    "AuthTypeName1"="FooID"
    "Keymgt_URI"="https://weblogin.foo.edu:2222"
    "Login_URI"="https://welogin.foo.edu"
    "Enterprise_Domain"=".foo.edu"
    "AuthType"="FooID"
    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).
  2. Double-click example.reg to enter your settings into the Windows registry.

Request Encryption Key (Using Keyclient.exe)

To obtain an encryption key for your application server:
  1. Open a command prompt.
  2. Run the following:
    cd C:Temp
    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 these files.
  3. If successful, keyclient will deposit a new DES key in your Pubcookie folder, e.g.
    %Systemroot%System32InetsrvPubcookiekeysappserver.example.edu
  4. 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:
  1. Start the Internet Service Manager (usually found in your IIS program folder).
  2. Right-click on the Web site into which you want to install the Pubcookie ISAPI filter and select Properties from the popup menu.
  3. In the ISAPI Filters tab, click Add.
  4. Enter Pubcookie for Filter Name.
  5. Click Browse and locate the Pubcookie DLL for Executable (e.g. %Systemroot%System32InetsrvPubcookiePubcookieFilter-3.0.0.dll).
  6. Click Ok. And click OK
  7. Right-click your Web site. Stop and restart it.
  8. 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:
  1. Copy the sample WebApp folder from C:Temp to your Web site’s root folder (e.g. C:inetpubwwwrootWebApp).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.
  2. To test authentication, start a Web browser and open /WebApp/ on your IIS server. For example:
    https://appserver.example.edu/Webapp/
    You should be redirected to your Pubcookie login server. After being authenticated, you should be redirected back.
  3. 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.
  4. 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 to:
    https://appserver.example.edu/Webapp/app-and-redirect-logout/
    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 response page.

Login Server Administration Guide

0
Included on this page:
Installation Instructions Supplemental Topics
  • Overview
  • What’s New
  • Upgrading & Compatibility
  • System Components
  • Basic Login Flavor
  • Authentication Types
  • Verifiers & Authentication Services
  • More About Abstractions
  • Building Components
  • SSL & Granting Key Pairs
  • Run-Time Config File Setup
  • Keyserver Setup
  • Key Management Methodology
  • Run Keyclient For Login Server
  • Deploying Login CGI
  • Testing Login CGI
  • Logging & Debugging
  • Login CGI Templates
  • Custom Login Messages
  • Browser Acceptance Configuration
  • Logout Configuration
  • Kiosk Configuration
  • Site Policy Configuration
  • Kerberos 5 Verifier Configuration
  • LDAP Verifier Configuration
  • Redundant Login Server Configuration
  • FastCGI Configuration
  • Supporting Application Servers
  • Appendix A: Apache Configuration
  • Appendix B: Permissions & Security
  • Appendix C: OpenSSL Commands
  • Appendix D: Revision History

Overview

This guide helps site administrators run a Pubcookie login server. Everything from setup and configuration to integration and customization is covered below. Application server administrators should refer to the Pubcookie Apache module guide or ISAPI filter guide for instructions on deploying a Pubcookie application server which authenticates using your local login server.

What’s New

Significant improvements and changes to the login server components included in Pubcookie 3.3.4:
  • Added support for 4096-bit private keys to login cgi.
  • Modified login cgi to log user’s IP address on Redirect log line.
Significant improvements and changes to the login server components included in Pubcookie 3.3.2d:
  • Applied security fixes to address vulnerability described in June 28, 2007 security advisory.
Significant improvements and changes to the login server components included in Pubcookie 3.3.2c:
  • Fixed strlcpy.c bug. Pubcookie’s implementation of strlcpy.c had a null termination bug when the source string (length – 1) exactly fits the destination string buffer.
  • Fixed Javascript call in login cgi when posting data back to the application server. Added ‘()’ to document.query.submit.
Significant improvements and changes to the login server components included in Pubcookie 3.3.2:
  • Added LDAPS support to LDAP verifier. Enable it with new ldap_tls config file variable. Configure TLS authentication with new ldap_key_fileldap_cert_file, and ldap_ca_file variables.
  • Fixed a bug to avoid a possible loop condition with unexpired PBC_CLEAR_COOKIE cookies.
Significant improvements and changes to the login server components included in Pubcookie 3.3.1:
  • New default login CGI templates with more standard XHTML, CSS, and utf-8 encoding.
  • Added clear_username_at_logout site policy to login cgi to control whether the username is cleared on logout.
  • Modified session reauthentication messaging. The login cgi now includes in the granting message whether or not it handled a reauthentication request.
  • Fixed null pointer usage in LDAP verifier when version is empty.
  • Modified login cgi to use more consistent audit logging strings. Prepended the “first kiss” timestamp to authentication success and failure log file messages.
  • Modified login cgi to allow ‘http:’ and ‘https:’ in app server uri query strings without percent encoding the colon.
Significant improvements and changes to the login server components included in Pubcookie 3.3.0a:
  • Applied security fixes to address vulnerabilities described in March 6, 2006 security advisory.
  • Fixed problems found in 3.3.0 release with “getcred” flavor’s Kerberos ticket passing.
Significant improvements and changes to the login server components included in Pubcookie 3.3.0:
  • Added AES encryption support. The login cgi will encrypt authentication messages with the encryption algorithm specified in the authentication request.
  • Changed login cgi to use AES encryption on its private login cookies.
  • Added PUBCOOKIE_LOGIN_CONFIG_FILE environment variable for defining an alternate config file for the login cgi.
  • Added support for the Apache module’s wildcard subdomain key encryption mode for large multi-user web-hosting environments.
  • Added kerberos5_extralife config file variable to extend the lifetime of delegated tickets past the SSO lifetime.
  • Added lowercase_username and uppercase_username site policies to the login cgi for modifying the case of the username.
  • Modified minimum LDAP_VENDOR_VERSION in configure script for better compatibility with Sun LDAP SDK.
  • Better handling of stray, malicious, and other spurious cookies. The login cgi will read all available login cookies to find a valid one. Previously, it only checked the first one, which might be invalid.
  • Other minor login cgi fixes to error handling and cookie clearing.
See doc/CHANGES.txt for bug fixes and other improvements.

Upgrading & Compatibility

In general, the login server components can be upgraded (built and installed) on a live system while safely maintaining your existing configuration file (PREFIX/config) and login templates (PREFIX/login_templates). Running make install on such a system will do the following:
  • install new keyserver, keyclient, and login cgi binaries into PREFIX/keyserverPREFIX/keyclient, and PREFIX/login/index.cgi, respectively.
  • install a set of (possibly updated) generic login templates is installed into PREFIX/login_templates.default but not into PREFIX/login_templates if it already exists.
  • install a new sample configuration file (PREFIX/config.login.sample).
Sites should compare their current config file and current templates against the new ones and resolve significant differences before copying the new login cgi and other binaries in production locations. Here are some additional compatibility notes for upgrading between specific versions:
Upgrading to 3.3.4:
User’s IP address added to Redirect log line: Sites that parse the login cgi’s log file data should be aware that the user’s IP address has been added to support additional business purposes (e.g. usage metrics, forensics, troubleshooting). Any scripts or programs that depend on the format of this data should be tested for compatibility prior to deploying the new version.
Upgrading to 3.3:
AES encryption impact on SSO: Sites upgrading to 3.3 should be aware that in version 3.3 the login cgi uses AES encryption on all login cookies, while earlier versions have used DES encryption. As a result, login cookies obtained by users prior to upgrading the login cgi will be invalid after the upgrade. This will affect some users’ SSO experience in the following ways: first, after the upgrade some users will have to reauthenticate where they might not have had to before; others might notice that the login page no longer remembers (i.e. no longer pre-fills) their username. Again, this is only around the time of the upgrade and only for browsing sessions that were started before the upgrade occurs.
Upgrading from version 3.2 to 3.3:
Template changes: The only template changes between versions 3.2 and 3.3 are those from the February 2006 login server security patch release. Therefore, sites upgrading an unpatched 3.2 login server (3.2.1a or earlier) to a patched 3.3 login server (3.3.0a or higher) should update their templates accordingly. Namely, explicit Content-Type definitions have been added to the following templates: errorloginnonpost_redirectnotokstatuspinit_response1, and logout_part1. Also, the entire HTML comment containing an unnecessary %url% variable substitution was removed from the nonpost_redirecttemplate. These files can all be found in PREFIX/login_templates.default.Sites upgrading to 3.3 from the patched 3.2.1b release or from a manually patched 3.2 version should already have these template changes as they are part of the patch.
Upgrading from version 3.0/3.1 to 3.3:
Template changes: Sites upgrading from 3.0/3.1 to version 3.3 must update their templates to account for changes that were introduced in versions 3.2 and carried into 3.3, as well as for those from the February 2006 login server security patch release. As noted above, the patch release updated to the following templates: errorloginnonpost_redirectnotokstatuspinit_response1, and logout_part1. These changes are on top of those from version 3.2, which introduced new variable substitutions in several templates. Sites should identify these substitutions by comparing these templates relative to their own production templates:
  • login (adds new %reason% and %version% variables)
  • form_expired (adds new %time variable)
  • logout_part2 (adds new %version% variable)
  • pinit_response2 (adds new %version% variable)
The following templates are new (in version 3.2, and therefore in 3.3) and should be reviewed and added to your production templates:
  • notoknotok_badagentnotok_form_multipartnotok_genericnotok_need_ssl
Finally, the following templates have been removed (in version 3.2, and therefore in 3.3) and therefore can be removed from your production template directory after upgrading:
  • notok_part1notok_part2
Compatibility note on version 3.1 relays:
Third-party relays deprecated: The need for the cgi-based relays introduced in version 3.1 to authenticate across DNS domains was redressed by the POST-based messaging method introduced in version 3.2 and, thenceforth, use of third-party 3.1 relays has been deprecated. To continue to support third-party relays at all, you must use the --enable-unsafe-relay configure option while building the login cgi. Preferably, upgrade all your application servers using third-party relays to version 3.2 or higher, and configure them to use the POST-based messaging method. Then there will be no need to support third-party relays in your login cgi.

System Components

The Pubcookie login server really consists of two separate components with separate purposes:
login server cgi
The Pubcookie login server uses a CGI program to handle browser requests. This CGI program, hereafter referred to as the login cgi or index.cgi, is compiled from C and is a site’s central Pubcookie component. End-users rely on it to authenticate; application servers rely on it for authentication assertions. The login cgi is typically powered by Apache HTTP Server software.
keyserver
The Pubcookie login server uses the keyserver component to generate and distribute symmetric encryption keys for participating servers, including your Pubcookie login server and all application servers. The keyserver runs as a service under inetd or xinetd.

Basic Login Flavor

The login cgi supports an abstraction called a login flavor. A login flavor encapsulates a specific set of functionality and features that influence how and when end-user authentication takes place. The distribution comes with one login flavor called the basic login flavor. This login flavor has a rich feature set, including single sign-on (SSO) user authentication, a pluggable backend authentication service interface, kiosk mode, and much more. This guide might, in fact, be described as a guide to the basic login flavor, it is so tailored to its installation and use.

Authentication Types

What the login cgi calls a login flavor, the application server components call an authentication type. The naming is rooted in Apache’s AuthType directive and it’s somewhat regrettable since they aren’t quite the same thing. For now it’s probably enough to say that, unless you build another login flavor, most application servers will be configured with a single choice of Pubcookie authentication types, one corresponding directly with the basic login flavor. How primary authentication takes place (that is, how usernames and passwords are actually authenticated) depends on how the basic login flavor verifies credentials with your backend authentication service.

Verifiers & Authentication Services

The basic login flavor performs username-and-password credential verification through a simple pluggable interface to backend authentication services. These plug-ins are called verifiers and the distribution comes with several:
kerberos_v5
verifies credentials using a Kerberos 5 KDC
ldap
verifies credentials using an LDAP server
shadow
verifies credentials using /etc/shadow
fork
verifies credentials using custom forked program
alwaystrue
verifies all credentials as successful. good for testing.
Compile-time decisions and run-time configuration determines which verifier is used by basic login flavor.

More About Abstractions

These login cgi abstractions help applications to remain independent of the method, or methods, used by the login server to authenticate user credentials. For example, a site might migrate from LDAP-based authentication to Kerberos authentication. It’s attractive to hide the transition from applications. Here applications would continue to use their institutional “netid” authentication type, corresponding with their site’s basic login flavor, while the login server administrators transition, transparently, from one verifier to another. Other sites may want to be able to choose from different backend authentication services. For example, the University of Washington uses the basic login flavor along side and a more secure flavor that uses SecurID in addition to username and password for primary authentication. Applications choose which flavor they want by configuring the appropriate authentication type.

Building Components

The configure script included in the distribution helps you build and install the login cgi and keyserver according to your platform and individual preferences. To build and install a barebones login server for evaluation and testing, run the following commands:
$ ./configure --enable-login --disable-apache
$ make
$ make install
This builds the login cgi with support for the basic flavor and the “alwaystrue” verifier. It also builds the keyserver and keyclient binaries. Files are installed, and directories created, according to the default installation directory prefix, henceforth called PREFIX, which defaults to /usr/local/pubcookie. Use the --prefix configure option to define an alternative location. Review the results by listing the installation PREFIX directory contents.
$ ls
total 240
-rw-r--r--  root  root    935 config                    # config file
-rw-r--r--  root  root    935 config.login.sample       # sample config
-rwxr-xr-x  root  root  92229 keyclient*                # keyclient
drwxr-xr-x  root  root   4096 keys/                     # keystore
-rwxr-xr-x  root  root  92929 keyserver*                # keyserver
drwxr-xr-x  root  root   4096 login/                    # login cgi dir
drwxr-xr-x  root  root   4096 login_templates/          # templates
drwxr-xr-x  root  root   4096 login_templates.default/  # originals
-rw-r--r--  root  root   2048 starter.key               # starter key

$ ls login
total 204
drwxr-xr-x  root  root   4096 images/                   # images
-rwxr-xr-x  root  root  99299 index.cgi*                # login cgi
Note: initial file permissions assigned by the installation process may not be acceptable for production use. Please refer to Appendix B: Permissions & Security section for a discussion of this subject. Continue through the setup and configration instructions using the alwaystrue verifier. After you’ve gained some familiarity with a working system, you can rebuild the login cgi to use a different verifier that goes against your local authentication service. Review the configure help for the build options.
$ ./configure --help
Refer also to the Kerberos, LDAP, and FastCGI configuration sections.

SSL & Granting Key Pairs

SSL key pairs have several functions in the operation of a Pubcookie login server. One key pair may suffice for all of them, but two key pairs often works better in practice. SSL key pair: The SSL private key and certificate used to SSL-enable Apache can be reused for the first keypair. This key pair is particularly suited for use with the keyclient and keyserver because the SSL public key certificate most likely has been signed and issued by a trusted Certificate Authority. The login cgi also uses this key pair, but only for signing and verifying “login” cookies. Note: the login cgi and keyserver cannot read encrypted RSA private keys because they can’t prompt for the passphrase. To reuse an encrypted SSL key, you’ll first have to remove the passphrase. Refer to Appendix C: OpenSSL Commands for help. The ssl_key_file and ssl_cert_file config file variables will point to these keys. Granting key pair: A second key pair is used to sign and verify “granting” cookies, the authentication assertions generated and signed by the login cgi and verified by application servers. Here the certificate issuer isn’t important, but the SSL public key certificate must be distributed to other servers. Therefore, a separate “granting” key pair is often used. Refer to Appendix C: OpenSSL Commands if you need help generating this key pair. The granting_cert_file and granting_key_file config file variables will point to these keys. Note: the key pairs described in this section (used for SSL and message signing primarily) are in addition to the symmetric encryption keys Pubcookie uses for data encryption.

Run-Time Config File Setup

The login cgi and keyserver read configuration settings from a run-time configuration file. The default location, PREFIX/config, is compiled in by default. The login cgi will use an alternate config file if a PUBCOOKIE_LOGIN_CONFIG_FILE environment variable defines one. This is useful when more than one logical login server is running on the same machine (using virutal hosts in Apache). The keyserver will use an alternate config file if the -f <filename> command-line option defines one. The config file format is one variable name-value pair per line, except where a trailing backslash  character continues a value to the next line. A sample config file appropriate for a login server is provided (see PREFIX/config or PREFIX/config.login.sample if you’re upgrading) as a starting point. It will look something like this:
# 1 is a good starting point
logging_level: 1

# the credential verifier used by the basic flavor
basic_verifier: alwaystrue

# SSL session keypair
ssl_key_file: /etc/httpd/conf/ssl.key/server.key
ssl_cert_file: /etc/httpd/conf/ssl.crt/server.crt

# granting keypair
granting_key_file: /usr/local/pubcookie/keys/pubcookie_granting.key
granting_cert_file: /usr/local/pubcookie/keys/pubcookie_granting.cert 

# login server config
login_uri: https://login.example.edu/
login_host: login.example.edu
enterprise_domain: .example.edu
logout_prog: /logout/index.cgi

# keyserver config
keymgt_uri: https://login.example.edu:2222
keyserver_client_list: login.example.edu trusted.example.edu
ssl_ca_file: /etc/httpd/conf/ssl.crt/ca-bundle.crt

# site-specific policies
default_l_expire: 8h
Begin editing your config file, using the config file variable reference as needed for examples and descriptions. Notes:
  • See how several variables in the example above are derived from the login server name, login.example.edu. This will be true for your config file too.
  • The example login server appears to be reusing its SSL key pair located in server.key and server.crt.
  • The example login server has a separate “granting” key pair. Refer to Appendix C: OpenSSL Commands if you need help generating this key pair.
  • The example keyserver appears to be using a file bundle of trusted Certificate Authorities (i.e., ca-bundle.crt). This file must contain all the trusted CA root certificates the site is using to verify keyclient certificates.

Keyserver Setup

Keyserver is designed to run as a service under inetd or xinetd. If you use inetd, add a line like the following to /etc/inetd.conf:
2222  stream  tcp  nowait  root  /usr/local/pubcookie/keyserver keyserver
If you use xinetd, create /etc/xinetd.d/keyserver with the following contents:
# description: pubcookie keyserver
service keyserver
{
	type			= UNLISTED
	protocol		= tcp
	port			= 2222
	disable			= no
	socket_type		= stream
	wait			= no
	user			= root
	group			= tty
	server			= /usr/local/pubcookie/keyserver
}
After adding the line to inetd.conf, or the file to xinetd, restart your inetd or xinetd service. Note: keyserver requires ssl_key_file and ssl_cert_file, and either ssl_ca_file or ssl_ca_path depending on how you handle trusted root CA certificates. Keyserver also uses granting_cert_file for distributing your “granting” certificate. And if you want control over which hosts can request keys, you can do so by defining a keyserver_client_list for authorizing new hosts.

Key Management Methodology

This section describes how symmetric encryption keys are managed by the Pubcookie keyserver. It issues keys to all participating servers, including all login servers and application servers. The keystore: A master copy of each 2048-byte host key is stored on the login server in its keystore, PREFIX/keys, in a filename based on the server’s SSL certificate’s Common Name. For example, a site with a login server and three application servers might have a keystore like this:
$ ls /usr/local/pubcookie/keys
total 204
-rw-r--r--  root  root   2048 weblogin.example.edu
-rw-r--r--  root  root   2048 appserver.example.edu
-rw-r--r--  root  root   2048 mail.example.edu
-rw-r--r--  root  root   2048 my.example.edu
-rw-r--r--  root  root    887 pubcookie_granting.key
-rw-r--r--  root  root   1224 pubcookie_granting.cert
Each host key can be used for DES encryption or AES encryption. The login cgi (as of version 3.3) uses AES encryption for login cookies. It uses either AES or DES for granting cookies, depending on the algorithm specified by the application server in its authentication request. New key generation: New host keys are generated and issued by the keyserver upon request. Running keyclient on a host initiates the request. If the keyclient host is authorized, and the keyclient and keyserver trust each other, the request is fulfilled. New keyclient host authorization: If the keyserver_client_list config variable is set, keyserver performs authorization on all keyclient requests. If it is not set, keyserver will issue host keys to any trusted keyclient. When authorization is enabled, grant-or-deny decisions are based on the presence a host in the keystore. If keyserver finds a host in the keystore, then that host can request a key. This seems like a catch-22: to create a new host key in the keystore, the key must already exist in the keystore. But it’s not: site administrators can use the keyclient’s “permit” option to authorize new servers to request host keys. For example:
$ keyclient -P new.example.edu
Host new.example.edu is permitted
This can be done manually by the login server administrator or by some kind of automated web-based registration service. The keyserver_client_list defines which hosts are authorized to use the permit option, allowing you to authorize new hosts without necessarily having to log in to the login server to do so. Trust: SSL/TLS mutual authentication Pubcookie uses elements of Public-Key Infrastructure (PKI) and SSL/TLS for mutual server authentication and data privacy between keyclient and keyserver. Trust is anchored by the Certificate Authorities used to sign, issue, and verify the certificates exchanged during keyclient connections. Mutual authentication means the keyclient and keyserver must identify each other. The keyclient must verify the SSL certificate presented by the keyserver. Likewise, the keyserver must verify the SSL certificates presented by keyclients. To do so, they both require trusted CA root certificates to do the verification. This is configured via ssl_ca_file or ssl_ca_path, which might point to your own institutional CA root certificate or pehaps the CA root certificate bundle that comes with OpenSSL, whatever you happen to be basing your trust policy on. Working with untrusted keyclients: An untrusted keyclient is one using a SSL certificate signed by a Certificate Authority the keyserver doesn’t trust. To allow such keyclients to request host keys without having to obtain another certificate, there’s a workaround. The login server administrator can cache the keyclient’s SSL certificate (public key) in the keystore. The keyserver can then use the public key itself to verify the keyclient. As a result, an otherwise untrusted keyclient can request host keys without changing the overall CA trust policy and configuration. Note: the keyclient’s -U cert_file option will upload a certificate to the keyserver, e.g.:
$ ./keyclient -U untrusted.example.edu.crt
This command can only be run from a trusted host, i.e. in the keyserver_client_list list.

Run Keyclient For Login Server

To generate a symmetric encryption key for your login server, copy the starter key found in the distribution into your keystore. Use your login_host name for the filename. For example:
$ cd /usr/local/pubcookie
$ cp starter.key keys/login.example.edu
The starter key allows keyserver to initialize when the keystore would otherwise be empty. Now you should be able to run keyclient to request a new host key for the login server based on your current config file settings:
$ ./keyclient
Set crypt key for login.example.edu
Note: if keyclient is unable to set a new host key, look in syslog for keyserver error messages.

Deploying Login CGI

The login cgi doesn’t depend on its own filename or location, so your primary concern in deploying it should be to create a simple URL that’s easy for users to recognize and trust with their password. The most common approach is to copy it from PREFIX/login/index.cgi to your Apache server’s root directory, resulting in a URL such as https://weblogin.example.edu/. The default HTML templates use relative links to locate the default stylesheet and inline images. These files are found in a media subdirectory. Copy the PREFIX/login/media directory to the same location as the login cgi. It should include one stylesheet file and three GIF images. Refer to Appendix A: Apache Configuration if you’re unfamiliar with the directives that control how Apache detects and handles cgi scripts, particularly as a directory index like index.cgi.

Testing Login CGI

The login cgi can be opened directly in a browser. This is sometimes called a pinit (for Pubcookie init, like kinit) since authentication is requested without being tied to an application. It’s a good way to test your current config file and verifier. Go ahead and try it now. The login page you see comes from the PREFIX/login_templates/login and PREFIX/login_templates/login_pinit templates. If authentication succeeds, congratulations, you now can deploy an application server using the Pubcookie Apache module or Pubcookie ISAPI Filter to test the components together. Then you can go on to build and configure another verifier that goes against your authentication service and customize the login cgi templates for your site. If authentication fails, don’t panic, look in your syslog for error messages from the login cgi and refer to the Logging & Debugging section for further advice.

Logging & Debugging

The login cgi uses syslog to log all messages. Logging can be configured using the logging_level variable. A value of 1 gets you basic audit activity such as logins and redirects which is most likely sufficient for normal operation. When additional debugging information is needed increase the value to 3. The keyserver also uses syslog and tends to log all critical error messages. Keyclient uses standard output for its messages.

Login CGI Templates

The login cgi reads HTML templates from the PREFIX/login_templates directory in order to create login, logout, error, and redirect pages. The login cgi will read from an alternative location if the template_root config file variable is defined. A set of generic, sample templates is copied into place during initial installation. A backup set is also copied to PREFIX/login_templates.default. Edit these templates (which represent “Example University”) to brand the login server for your organization and to meet local web design standards. Refer to the login cgi template reference for descriptions of each template.

Custom Login Messages

This is all about branding. Some application owners require branding of the login page with their own login prompt text and icons. The login cgi support this capability through the use of custom login message templates (small HTML snippets) configured on the login server. They can’t take over the entire design of the login page, but it does provide a place for friendlier, custom messages. A custom login message applies to a single application, so the corresponding template is stored in a file according to the server name and application id. The file path is based on the custom_login_message_dirconfiguration variable (the directory containing all the custom login message templates, which defaults to the same directory as all the other login templates). The filename is based on the custom_login_file_prefix configuration variable (the filename prefix for all custom login message templates) plus the server name and application id. For example, to configure a custom login message for an application on appserver.example.edu with an application id of testapp, you would place the custom message (HTML snippet) in the following file (based on default values, of course):
PREFIX/login_templates/custom_login_msg-appserver.example.ed-testapp
You can see where custom login messages are positioned relative to other elements on the login page by viewing the HTML source of the login template. They come just before the reason the user has to authenticate.

Browser Acceptance Configuration

The optional PREFIX/ok_browsers file contains a list of browsers accepted by the login cgi. This file provides a way to block browsers that either have a known security flaw (i.e., don’t forget cookies when they should) or don’t work with Pubcookie. The ok_browsers file is optional.

Logout Configuration

The login cgi handles logout requests initiated by, and redirected from, applications configured with Pubcookie’s per-application logout functionality. Handling these logout requests is built in; no configuration is necessary to the login cgi itself. However, through additional configuration you can create a separate, direct logout URL for your login server (e.g. https://weblogin.example.edu/logout). You can also tailor the logout response messages for your favorite applications. Those are the two subjects of this section. Note: Pubcookie does not support “global” logout, that is, logout of all sessions, all cookies, all at once. Rather, it supports per-application-session logout with optional ability also to logout of the login server. Therefore, users still must be educated not to leave their browsers open and unattended without proper precautions such as locking their computer and using password-protected screensavers. Exiting the browser remains the best way for users to get logged out of everything at once. Configuring a Direct Logout URI: If you want to provide a URL where users can go directly to clear their single sign-on session (by way of clearning their “login” cookie), it can be created with the logout_prog config variable and a Unix symbolic link. Here’s an example. Suppose the login cgi has been installed in the DocumentRoot directory (e.g. in /var/www/html) with a URL of https://weblogin.example.edu. To create a logout URI of /logout/ just below that, i.e., https://weblogin.example.edu/logout/, you’d do this: Change to the appropriate directory, create the subdirectory, and make the symbolic link to your login cgi:
$ cd /var/www/html
$ mkdir logout
$ cd logout
$ ln -s ../index.cgi index.cgi
Adjust the directory according to the location of your login cgi. Now any request to /logout/ on the server will map to your login cgi. Now add the appropriate logout_prog variable to your config file:
logout_prog: /logout/index.cgi
Customizing Logout Responses For Special Apps: The login cgi builds logout response pages from several templates. One template, logout_app, which is the most specific to each application, can be overridden on a per-application basis, as configured and identified by the originating server name and application id. It requires one app_logout_string config file variable for each application, where the server name and id are tacked on using dashes. For example:
# custom logout msgs
app_logout_string-appserver.example.edu-testapp: 
          <font size="+1">Testapp logout worked just fine.</font>
app_logout_string-webmail.example.edu-webmail: 
          <font size="+1">Webmail Logout Successful!</font>
Note: Since the login cgi reads the config file and its HTML templates on each request, there’s no need to recompile the login cgi in order to modify response messages.

Kiosk Configuration

Use the kiosk variable to apply a site policy for reduced single sign-on duration for identified kiosks. The login cgi supports matching by user-agent string, remote IP address, or IP address ranges. For example:
kiosk:   20m Safari/85.6 
         15m Safari 
         10m ExampleKiosk 140.142.14.39 140.142.21.* 
         1h  140.142.15.10-200
This sets a curiously elaborate, but nonetheless illustrative, kiosk policy: a 20-minute SSO duration for Safari 85.6, a 15-minute SSO for all other versions of Safari, a 10-minute SSO to remote browsers with “ExampleKiosk” in the user-agent string as well as to the remote IP address 140.142.14.39 and the 140.142.21 subdomain, and a one-hour SSO duration for IP addresses in the range 140.142.15.10-200. Matching by user-agent string is particularly useful for applying reduced SSO to managed kiosks that have a locally customized user-agent string such as:
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; ExampleKiosk; Windows NT 5.0)
How to customize user-agent strings is beyond the scope of this guide, but resources and tools, such as the Internet Explorer Administration Kit, do exist to help with this task.

Site Policy Configuration

This section highlights some of the possible site policies you can define in your config file. These options may be overlooked, but they can enhance the user experience and shape the security policy of your login server.
  • Use default_l_expire to define your default single sign-on duration. Primary authentication occurs when user-provided credentials are verified directly. Subsequent authentication is based on checking the “login” cookie. This setting defines how long this cookie is valid.
  • Use form_expire_time to define how long users have to log in. Taking too long will result in a new login form (with the form_expired template message included). The default expiration is 60 seconds.
  • Use static_user_field to define the editability of the userid field during a single browsing session. You may want to allow some flexibility or force users to close the browser before switching between users.
  • Use the retain_username_on_failed_authn to define whether the userid is retained after a failed login attempt. Users will appreciate this if they mistyped their password, not their userid.
  • Use trim_username_to_atsign to define whether users can enter a userid that looks like an email address. Sites that aren’t verifying full Kerberos principals (e.g. joe@example.edu) or userids that look like email addresses can use this feature to provide some flexibility in this regard, i.e., to trim off the extra realm info the user added and verify just the proper userid.
  • Use lowercase_username or uppercase_username to change the userid to lowercase or uppercase.
Refer to the config file variable reference to review these variables and the values they take.

Kerberos 5 Verifier Configuration

To build the login cgi with support for the Kerberos 5 verifier, run the configure script with the Kerberos option enabled:
./configure --enable-login --disable-apache --enable-krb5
If needed, the configure script has other options for adjusting the location of the Kerberos header files and libraries. To configure the login cgi to use the Kerberos verifier, edit your config file and set basic_verifier to kerberos_v5. Additionally, two other config file variables control the Kerberos 5 verifier: kerberos5_service_nameand kerberos5_keytab. For example:
# kerberos verifier config
basic_verifier: kerberos_v5
kerberos5_service_name: pubcookie
kerberos5_keytab: /usr/local/pubcookie/keys/pubcookie.keytab
Enable the append_realm variable if you want the Kerberos authentication realm to be appended to the user name after authentication but before issuing cookies (i.e., target servers will receive user@REALM.) Use the default_realm variable to define a default Kerberos authentication realm to pass to the verifier when none is submitted via the login form. To authenticate responses from your Kerberos server, the login server and Kerberos server must share a service key. You can use an existing service key or generate a new one with the help of your Kerberos administrator. Keep in mind that the keytab file that contains your service key must be readable by the login cgi. Since the login cgi will most likely run as a non-root user, it’s recommended that you use a service key other than the “host” service key typically stored in /etc/krb5.keytab. Similar to user keys, service keys have a principal of the form <service_name>/<hostname>@<realm>. The hostname is the fully qualified hostname for your login server, and the realm is the Kerberos realm. But the service name is what counts most to the Kerberos 5 verifier. Your service name can be set with the kerberos5_service_name variable. Contact your local Kerberos domain administrator if you need help creating a service key, generating a keytab file, or otherwise configuring Kerberos (e.g. /etc/krb5.conf) on your login server. See doc/krb5-getcred.html for details on how to configure and use Kerberos credential passing.

LDAP Verifier Configuration

To build the login cgi with support for the LDAP verifier, run the configure script with the LDAP option enabled:
./configure --enable-login --disable-apache --enable-ldap
Note: Other configure options can help you specify the location of your LDAP header files and libraries. See ./configure --help. To configure the login cgi to use the LDAP verifier, set basic_verifier to ldap in your config file. To configure the LDAP verifier itself, add an ldap_uri to your config file. This variable defines how the verifier connects to your LDAP directory. To enable LDAPS with TLS authentication, configure ldap_tls,ldap_key_fileldap_cert_file, and ldap_ca_file.
# ldap verifier config
basic_verifier: ldap
ldap_uri: ldaps://host/o=searchbase???(uid=%s)?x-BindDN=Bind%20DN,x-Password=Password
Note: LDAP in general is not case sensitive, so most implementations don’t enforce case sensitivity on the username (uid) attribute. This may result in usernames of mixed case being sent to application servers for the same authenticated user (e.g. jon, Jon, jOn). To prevent this, use the lowercase_username site policy to change the username entered to lowercase.

Redundant Login Server Configuration

The login cgi and keyserver can be deployed in a redundant configuration, provided that they share the same cluster name and settings. Use the login_servers variable to configure keyserver to push new host keys to its peers.

FastCGI Configuration

The login cgi can run as a FastCGI process. This allows one or more instances of the login cgi to persist and handle many requests rather than just one. FastCGI support is enabled with the --with-fcgi=<path to fcgi> option. Example Apache configuration follows below; modify as needed.
LoadModule fastcgi_module     libexec/mod_fastcgi.so
FastCgiConfig 
       -appConnTimeout 0 
       -idle-Timeout 30 
       -init-start-delay 2 
       -killInterval 300 
       -listen-Queue-Depth 50 
       -maxProcesses 10 
       -maxClassProcesses 2 
       -minProcesses 1 
       -startDelay 10

Supporting Application Servers

To support application servers, other system administrators will need to know the location of your login server, keyserver, and how trust is handled on your keyserver. That is, which CAs the keyserver trusts to verify keyclient certificates; and which CA can be used by the keyclient to verify your keyserver certificate.

Appendix A: Apache Configuration

The default filename for the login cgi, index.cgi, is a common name for a cgi program that is executed when a directory’s URL is requested. The DirectoryIndex directive defines how Apache handles such requests, typically choosing the first file it finds in its DirectoryIndex list. With appropriate configuration, this can be your login cgi. For example, you might use the follow DirectoryIndex directive:
DirectoryIndex index.cgi index.html
Apache also needs to know how to identify cgi scripts by the .cgi filename extension. Some distributions of Apache have the cgi handler disabled. Make sure the following line is in your httpd.conf and not commented out.
AddHandler cgi-script .cgi
Finally, Apache must allow execution of cgi scripts in the directory where the login cgi is located. If it’s outside of a ScriptAlias directory, you can control this with the Options directive.
Options Indexes FollowSymLinks ExecCGI

Appendix B: Permissions & Security

Due to the important nature of the Pubcookie login server, the only other services that should be run on the same system are those which receive an equally high level of scrutiny for security. Some of the login cgi’s supporting files are sensitive, particularly the two private keys, ssl_key_file and granting_key_file. In a production environment, non-root users shouldn’t be able to read these files. However, in a typical Apache configuration the login cgi runs within a restricted user context defined by the User and Group server directives. They are usually set to some non-privileged user and group (e.g. nobody.nobody). One approach to permissions is simply to make the sensitive files owned and readable by the non-privileged Apache user (nobody.nobody and octal 600700 for the keys directory).
drwx------  nobody nobody   4096 keys/ 
-rw-------  nobody nobody   4096 keys/pubcookie_granting.key
-rw-------  nobody nobody   4096 keys/pubcookie_session.key
Another approach is to run Apache as a non-privileged user but use a group that no users are allowed to be in (e.g. nobody.www where no users are in the www group). Then sensitive files can be restricted to just root and to the empty group (root.www and octal 640750 for the keys directory). Since the login cgi runs in the context of the group, it can read the files it needs to.
drwxr-x---  root   www      4096 keys/ 
-rw-r-----  root   www      4096 keys/pubcookie_granting.key
-rw-r-----  root   www      4096 keys/pubcookie_session.key
Note: since the keyserver is run by inetd or xinetd, it is most likely run as root and therefore can read and write supporting files as needed.

Appendix C: OpenSSL Commands

To generate a new RSA private key and self-signed public key certificate, (for example, for the “granting” key pair), change to the PREFIX/keys directory and use the following OpenSSL command as an example:
$ cd /usr/local/pubcookie/keys
$ openssl req -new -x509 -out pubcookie_granting.cert 
    -newkey rsa:1024 -nodes -keyout pubcookie_granting.key
To remove the pass phrase on an SSL private key:
$ openssl rsa -in server.key -out unencrypted.key
The man pages for x509rsa, and req have many other useful OpenSSL command examples.

Appendix D: Version History

Significant improvements and changes to the login server components included in Pubcookie 3.2.1:
  • Added kerserver support for subjectAltName wildcards.
  • Fixed login cgi to put redirect messages into the normal audit logging stream.
  • Added login_host_cookie_domain to make login cookie domain configurable.
  • Added remote realm, if present, to authentication success message in flavor_basic logging.
  • Fixed LDAP verifier to default to LDAPv3 for all LDAP SDKs and added “x-Version” parameter to the LDAP URL.
  • Revised “fork” verifier to pass username and password via stdin to the forked executable. The config file variable has been changed from fork_exe to verify_exe to avoid accidentally running the wrong executable.
Significant improvements and changes to the login server components included in Pubcookie 3.2.0:
  • Added support for custom per-application login messages
  • Added keyserver support to allow keyclient authentication by wildcard certificates and Subject Alt Names
  • Added keyserver support to allow keyclient certificates signed by untrusted CAs to cache a public key on the keyserver and use it in server authentication
  • Added keyclient -U <certfile> option for admins to upload a public key certificate to the keyserver
  • Added version string to login server template as HTML comment
  • Improved POST-based messaging between application servers and login server
  • Deprecated the use of third-party relay cgi

Apache Module Installation Guide

0
Apache Module Installation Guide
Included on this page:
  • Overview
  • What’s New
  • Compatibility Notes
  • Upgrading
  • Prerequisites
  • System Requirements
  • Confirm SSL Support
  • Build & Install
  • Run Keyclient
  • Configuration (httpd.conf)
  • Start Apache
  • Test Pubcookie Authentication
  • Logout Configuration
  • Cross-Domain Relay Configuration
  • Virtual Host Configuration
  • Clustered Host Configuration
  • Wildcard Subdomain Key Configuration
  • Troubleshooting
  • Appendix A: How to Enable SSL
  • Appendix B: Configuration For Abbreviated Domain Names

Overview

This guide helps Apache HTTP server administrators install and use the Pubcookie Apache module, herein referred to as simply the module, but also commonly known as mod_pubcookie. The topics covered below will help you to :
  • Build and install the module for use with either Apache 1.3 or 2.0;
  • Use the Pubcookie keyclient to obtain a symmetric encryption key from your local Pubcookie keyserver and retrieve your site’s Pubcookie “granting” certificate;
  • Configure the module by adding directives to Apache’s httpd.conf;
  • Start Apache and test the module to confirm that authentication is working.
Site administrators should refer to the login server guide for instructions on deploying a Pubcookie login server.

What’s New

Significant improvements and changes included in Pubcookie 3.3.4:
  • Fix handling of angle brackets in the argument names in POST data.
Significant improvements and changes included in Pubcookie 3.3.3:
  • Fixed handling of requests to /favicon.ico when Pubcookie authentication isn’t enabled.
  • Fixed internal redirects to forward mod_pubcookie headers to the new request record.
  • Fixed POST login method to preserve and restore query string as well as post data.
  • Added some type casts to avoid compiler warnings.
Significant improvements and changes included in Pubcookie 3.3.2d:
  • Fixed bug in verify_url function causing some characters such as colons to be converted to other chars during login.
Significant improvements and changes included in Pubcookie 3.3.2c:
  • Fixed bug in use of output filters introduced in version 3.3.2, in Apache 2.0.49 and higher, whereby headers set in the ‘filter’ mode are dropped when the module creates response content, logouts, errors, etc.
Significant improvements and changes included in Pubcookie 3.3.2b:
  • Modified Apache module to handle ‘+’ chars in base-64-encoded path. This fixes possible truncations of uri’s sent through the login process.
Significant improvements and changes included in Pubcookie 3.3.2a:
  • Modified Apache module to verify that the login server sends a non-empty userid in the granting reply, unless PubcookieNoPrompt is on.
  • Modifed Apache module to url-encode ‘+’ chars after base64-encoding query strings. This fixes possible truncations of uri’s sent through the login process.
  • Fixed out of place “char *datestr” declaration.
Significant improvements and changes included in Pubcookie 3.3.2:
  • Improved Apache 2.x compatibility. For Apache 2.0.49 and above, the module sets output headers in an output filter. This provides better interoperability with other modules too, in particular, mod_proxy_ajp.
  • Added PubcookieNoCleanCreds directive to allows an application to handle flavor_getcred credential cleanup.
Significant improvements and changes included in Pubcookie 3.3.1:
  • Added PubcookieCatenateAppIDs directive
  • Improved Makefile for Apache 2.2 builds.
  • Modified session reauthentication messaging. The module now verifies that the login cgi handled a reauthentication request when session reauthentication is configured. (Requires 3.3.1 or higher login server.)
  • Fixed bug in AES encryption mode that causes session cookies to be unreadable when PubcookieInactiveExpire is on.
  • Modified the module’s startup process such that it halts if security initialization fails (e.g., PubcookieSessionCertFile doesn’t exist).
Significant improvements and changes included in Pubcookie 3.3.0a:
  • Fixed encryption problems found with some virtual host configurations.
  • Modified POST PubcookieLoginMethod to use HTTP 302 redirects instead of meta-refresh on redirect back to the resource.
  • Updated the module’s handling of output values when printing redirect pages.
Significant improvements and changes included in Pubcookie 3.3.0:
  • Added AES encryption as the default encryption algorithm requested by and used by the module. To interoperate with earlier versions of the login server, set PubcookieEncryption to DES or build the module with the --enable-default-des configure option.
  • Removed pre-session cookie countermeasure when using POST PubcookieLoginMethod. It’s unneeded complexity and in this case an unnecessary countermeasure.
  • Added wildcard subdomain key capability for large multi-user web-hosting environments.
  • Better handling of stray, malicious, and other spurious cookies. The module will read all available session, pre-session, and granting cookies, until it finds a valid one. Previously it only checked the first one, which may be invalid.
See doc/CHANGES.txt for bug fixes and other improvements.

Compatibility Notes

Here are some compatibility notes for version 3.3:
Compatibility note on version 3.3 encryption algorithms:
The version 3.3 module supports different encryption algorithms. AES encryption is the default. However, earlier versions of the login server only support one algorithm, DES, so you will have to determine the version of your login server and configure the PubcookieEncryption directive accordingly.
Compatibility note on version 3.1 relays:
The need for the cgi-based relays introduced in version 3.1 to authenticate across DNS domains was redressed by the POST-based messaging method introduced in version 3.2. Use of third-party 3.1 relays has therefore been deprecated. A third-party relay is any relay not hosted on the same server that requests authentication. Application servers using third-party relays are strongly encouraged to upgrade to version 3.2 or higher and use the POST-based messaging method.

Upgrading

In general (note exceptions below) upgrading a working installation of the module requires very few, if any, changes to the current Apache configuration, and you can typically reuse your current Pubcookie granting certificate and symmetric encryption key too. Here are some compatibility notes for upgrading between specific versions:
Upgrading from version 3.0/3.1/3.2 to 3.3:
Apache servers being upgraded from version 3.0/3.1/3.2 to version 3.3 should be aware that version 3.3 expects and uses AES encryption by default. If your login server is version 3.3 or higher, interoperability isn’t a concern. However, to interoperate with earlier version of login server, you should configure PubcookieEncryption to use DES encryption, or, if you don’t want to make any Apache configuration changes, you should build the module using the --enable-default-des configure option, which forces the module to use DES encryption by default.If your login server is version 3.3 higher and therefore allows you to use AES encryption, you should note that session cookies encrypted with DES cannot be unencrypted with AES. As a result, pre-session and session cookies obtained by users prior to upgrading the module will be invalid after the upgrade. Therefore, some users will be redirected through the login server to establish a new session. Clustered hosts should be upgraded with special care to keep all cluster members using the same encryption method. Note: You do not have to request a new encryption key to use version 3.3. Your current host key works equally well for AES and DES encryption.
Upgrading from version 1.77 to 3.3:
Apache servers being upgraded from earlier versions of the module (classic versions, such as version 1.77) may require minor configuration changes. Review the Apache configuration section closely. Also review the sections on virtual host configuration and clustered host configuration if they apply to your environment.Apache servers being upgraded from earlier versions should also be aware of the switch to AES encryption noted in the section above. Also recall that version 1.77 requires an encryption key specific to your primary IP address. If you want to be able to rollback to version 1.77 more easily, you should keep your current key intact on your server as well as on your site’s Pubcookie login server. To do so, use the keyclient’s -d option when downloading the current key; otherwise the keyserver will generate a new one that isn’t compatible with version 1.77.

Prerequisites

The module relies on additional infrastructure at your site. Here are some general prerequisites that, if fulfilled, will lead to a smooth, successful installation.
  • Determine the location of your site’s Pubcookie login server. You’ll need this URL to configure the module. You may also want to find out its version, for compatibility reasons, and to know what features it supports.
  • Determine the location of your site’s Pubcookie keyserver. You’ll need this URL to request a symmetric encryption key that your server will share with your login server. Depending on the keyserver version and site policy, you may also need to ask your administrator to “permit” your server to request keys.
  • Determine how trust is handled by your site’s Pubcookie keyserver. You’ll need to know which Certificate Authorities the keyserver trusts to verify certificates. Similarly, you’ll need to know which Certificate Authority can verify the keyserver’s certificate. Ask your administrator for guidelines; it’ll save you time and effort.
  • Determine how your site distributes its Pubcookie “granting” certificate. You’ll need a copy of this certificate to verify the “granting” cookies signed and sent by your site’s login server. You may be able to download it from your keyserver, or you may have to obtain it manually. Ask your administrator which method to use.
Note: one additional suggestion for more advanced uses. Review the sections on virtual host configuration or clustered host configuration now if either of those scenarios apply. The information will help you think about and tailor the simple case instructions while you go through them.

System Requirements

The module has the following system requirements:
  • Unix platform.
  • Accurate system time.
  • OpenSSL library.
  • Apache HTTP Server. Versions 1.3 and 2.0.49 and above are supported.
  • SSL enabled web server. The mod_ssl package is recommended. See our FAQ for information about using Apache-SSL.
  • SSL keypair. An SSL server certificate and private key.Note: Pubcookie uses elements of public-key infrastructure (PKI) for server authentication and data privacy. Therefore, as you might expect, your SSL server certificate and private key can play a role here. However, a self-signed certificate may not pass muster.
  • Domain name registered in DNS (e.g. appserver.example.edu) .Note: If your server doesn’t share a common DNS subdomain (e.g. .example.edu) with your site’s Pubcookie login server (e.g. weblogin.example.edu) or if your enterprise DNS domain is in a country code top-level domain (e.g. example.ca) then you should use POST-based messaging configured by the PubcookieLoginMethod.

Confirm SSL Support

Before you build and install the module, confirm that your SSL configuration is working and that Apache responds to HTTPS requests. The module requires a functioning SSL-enabled server. If your Apache server does not already support SSL, refer to Appendix A: How to Enable SSL for guidelines.

Build & Install

The configure script included in the distribution helps you build and install the module according to your platform, Apache version, and individual preferences. It also helps you build and install the Pubcookie keyclient which will be used to obtain a symmetric encryption key for your server. Step-by-step instructions follow below for building and installing these components on your server, including specific details for building the module as a Dynamic Shared Object (DSO) or statically compiling the module into Apache itself.
  1. Download the Pubcookie source code distribution.
  2. Unzip and untar the source files.
    $ gzip -d pubcookie-3.2.0.tar.gz
    $ tar xvf pubcookie-3.2.0.tar
    $ cd pubcookie-3.2.0
    Note: You can run the configure script and make the module (or new httpd binary) while logged in to a non-privileged user account, but you may want to be root to do the install.
  3. Decide if you want to build a DSO and load it dynamically using Apache’s DSO support or statically compile the module into a new httpd binary.To build a DSO module: The default configuremakemake install process builds the DSO (mod_pubcookie.so) using apxs as found on your system. It also builds the keyclient and uses the default installation prefix,/usr/local/pubcookie, as the installation target directory.Use configuration options to customize as needed. For example:
    $ ./configure 
        --enable-apache 
        --prefix=/usr/local/pubcookie 
        --with-apxs=/path/to/apxs 
        --with-ssl=/path/to/openssl
    $ make
    $ make install
    Notes:
    • The --prefix option defines the installation prefix where supporting files are installed and found.
    • The configure script will detect your version of Apache (1.3 vs 2.0) based on apxs as found on your system. Use --with-apxs when you have more than one copy or version of Apache installed on your system.
    • Use the --with-ssl option when you have more than one version of OpenSSL installed on your system.
    • Running make install uses apxs (Apache 1.3) or libtool (Apache 2.0) to copy the DSO to Apache’s modules (libexec) directory. With Apache 1.3, it also adds inactive LoadModule and AddModule directives to your httpd.conf file.
    To compile the module statically: The configure script can also prepare the source files to statically compile the module into Apache at build-time. Here the configure script uses the --with-apache-src option to copy the module’s source files to your Apache source directory. It also creates a Makefile to build and install the keyclient. The process might look something like this:
    # add module src to Apache and generate Makefile for keyclient
    $ ./configure 
        --enable-apache 
        --prefix=/usr/local/pubcookie 
        --with-apache-src=/path/to/apache/src 
        --with-ssl=/path/to/openssl
    
    # build, install, setup keyclient
    $ make
    $ make install
    
    # configure, make, and install Apache
    $ cd /path/to/apache
    $ SSL_BASE=/usr/local/openssl ./configure 
        --prefix=/path/to/install/apache 
        --enable-module=ssl 
        --activate-module=src/modules/pubcookie/libpubcookie.a 
       [...more options...]
    $ make 
    $ make install
    Notes:
    • You still run make and make install while in the pubcookie directory because you need to build and install the keyclient. No worries, it won’t build the module or Apache.
  4. Okay, you’ve reached a useful checkpoint. Lets pause to assess your progress.At this point you’ve either built a new DSO module or a new httpd binary. You’ve also built and installed the keyclient into the installation target directory. List this directory now to see that you have a keyclient binary and a new keys subdirectory:
    $ ls -F /usr/local/pubcookie
    keyclient*      keys/
    Note: Permissions. If you initially start Apache as root and use the User directive to switch to a non-root user, you can lock down your pubcookie directory permissions so that non-root users cannot read its contents.

Run Keyclient

Pubookie solves the problem of securely distributing symmetric encryption keys by introducing a keyserver. Participating servers make authenticated SSL/TLS connections to keyserver to obtain a host key. This section describes how to configure and run the Pubcookie keyclient utility to request keys from your local keyserver. Tip: Ask your keyserver administrator for advice about configuring the keyclient. It’s particularly important to know the Certificate Authority that signed (and therefore can verify) the keyserver’s certificate. To configure the keyclient:
  1. The keyclient accepts command-line options, but it’s generally easier to configure by specifying values in a separate text configuration file. Go ahead and create one now:
    $ cd /usr/local/pubcookie
    $ pico config
    Note: keyclient uses a built-in location, based on your original installation prefix, to look for a config file and to store host keys. Adjust the path above accordingly.
  2. Add the following configuration variables and adjust their values according to your site:
    # 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
    Notes:
    • To negotiate the SSL/TLS connection to your keyserver, the SSL certificate used by the keyclient (i.e., ssl_cert_file) must be signed by a Certificate Authority trusted by your site’s keyserver.
    • Likewise, the certificate presented by the keyserver must be signed by a CA trusted by your keyclient; that is, it will be verified using the CA root certificates define by ssl_ca_file or ssl_ca_path. Ask your site administrator what CA root certificate should be used to verify your keyserver certificate.
  3. Save the changes to your config file.
To request a new symmetric encryption key:
  1. If necessary, ask your Pubcookie keyserver administrator to “permit” your server so that it can request a host key for itself. This requirement will depend on the local policy for server registration as well as the version of keyserver being used.
  2. Run keyclient to request a new key:
    $ ./keyclient
    Set crypt key for appserver.example.edu
    Notes:
    • Use the keyclient’s -f <filename> option (requires version 3.2.1 or higher) to specify an alternate config file.
    • The keyclient uses the installation prefix by default to determine the path to your keys directory. You can override this using the keydir config file variable.
    • The key’s filename is derived from your certificate’s Common Name field.
    • If you use a wild card certificate (e.g., the CN is *.subdomain.example.edu), use the -H <hostname> keyclient option to specify your actual server name (e.g., -H host.subdomain.example.edu).
    • Likewise, if your server name is one of several names in your certificate’s Subject Alt Name field, use the -H <hostname> keyclient option to specify the server name that should be used for the key request.
    • If keyclient says “NO you (appserver.example.edu) are not authorized for keys“, contact your local site administrator to learn how to register your application server.
    If keyclient fails for any other reason, note any error messages and refer to the Troubleshooting section below.
  3. List the contents of your keys directory to find the new key:
    $ ls /usr/local/pubcookie/keys
    appserver.example.edu
    Notes:
    • The key’s filename is derived from your certificate’s Common Name field which should match the domain name visitor’s see in the URL for your website.
    • During configuration, this key is found within the directory defined by the PubcookieKeyDir directive or corresponds directly with the PubcookieCryptKeyFile directive.
    • Each key works fine with either encryption method offered by the PubcookieEncryption directive.

To download your site’s Pubcookie “granting” certificate:

The module uses your Pubcookie login server’s “granting” certificate to verify the digital signature of “granting” cookies sent from the login server to your server.
  1. Run keyclient with the -G option to retrieve your site’s “granting” certificate.
    $ cd /usr/local/pubcookie
    $ ./keyclient -G keys/pubcookie_granting.cert
    Granting cert saved to keys/pubcookie_granting.cert
    Notes:
    • If you use a wild card certificate or a Subject Alt Name, use the same -H option used to request your encryption key.
    • During configuration, this certificate corresponds with the PubcookieGrantingCertFile directive in httpd.conf.
If keyclient cannot download your “granting” certificate, your keyserver may not support this retrieval method and you’ll have to obtain a copy manually.

Configuration (httpd.conf)

Configuring the module begins with your main Apache server configuration httpd.conf file. This section describes what you need to add to this file.
  1. Edit your Apache server configuration file (httpd.conf), e.g.:
    $ pico httpd.conf
  2. (For DSO method only.) When working with the module as a DSO, the installation process uses apxs (Apache 1.3) or libtool (Apache 2.0) to install the module into Apache’s modules (libexec) directory. Now the module needs a little configuration based on your version of Apache.Apache 1.3: LoadModule & AddModule With Apache 1.3, installation also adds new, but initially inactive, LoadModule and AddModule directives to your httpd.conf file. Find these directives. Make sure they landed in the right location. And uncomment them to activate them. 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. Warning: if your LoadModule and AddModule directives for the module 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. Apache 2.0: LoadModule With Apache 2.0, add a LoadModule directive to your server config wherever it makes sense to do so. The AddModule directive no longer exists in Apache 2.0, so don’t add one of those.
    LoadModule pubcookie_module   modules/mod_pubcookie.so
  3. Add a new section in httpd.conf for configuring the module:
    <IfDefine HAVE_SSL>
    <IfModule mod_pubcookie.c>
    
    #
    # Pubcookie configuration section
    #
    
    PubcookieGrantingCertFile /usr/local/pubcookie/keys/pubcookie_granting.cert
    PubcookieSessionKeyFile /etc/httpd/conf/ssl.key/appserver.key
    PubcookieSessionCertFile /etc/httpd/conf/ssl.crt/appserver.crt
    PubcookieKeyDir /usr/local/pubcookie/keys/
    
    PubcookieLogin https://weblogin.example.edu/
    PubcookieLoginMethod POST
    PubcookieDomain .example.edu
    PubcookieEncryption AES
    PubcookieAuthTypeNames EGNetID
    
    # Disable inactivity timeout by default
    <Directory "/var/www/html">
    PubcookieInactiveExpire -1
    </Directory>
    
    </IfModule>
    </IfDefine>
    Notes:
    • These are recommended configuration directives, but they’re not all required to initialize the module. It’s a good exercise, however, to configure them explicitly, so you know what’s going on.
    • PubcookieEncryption defines the encryption algorithm used by the module. Since the module chooses the algorithm that the login server will use to encrypt messages, it’s important to get this one correct. (See compatibility notes.)
    • PubcookieLoginMethod defines the messaging method used by the module. Servers in country code top-level domains (e.g. .ca.de) must use the POST method.
    • PubcookieDomain is unnecessary if you use POST as your PubcookieLoginMethod.
    • PubcookieAuthTypeNames defines the authentication types that the module enables as additional arguments to the AuthType directive. (EGNetID just happens to be what they use at Example State University.) Each type you define should correspond with a “login flavor” offered by your login server. Most sites have just one.
    • Turning off the inactivity expiration via the PubcookieInactiveExpire directive provides a modest performance boost, since session cookies aren’t signed as often when there is no inactivity timeout. Applications that require an inactivity timeout can always override the default setting.
    • Warning: If your LoadModule and AddModule directives reside within an <IfDefine HAVE_SSL> block directive then all the module’s configuration directives must also reside within an <IfDefine HAVE_SSL>block directive. This is the convention used throughout this guide.
    • Permissions. If you initially start Apache as root and use the User directive to switch to a non-root user, the module’s supporting files can be made readable only by root. If you start Apache as a non-root user, then that user must be able to read the supporting file.
    • The RSA private key represented by PubcookieSessionKeyFile cannot be encrypted. The module won’t initialize, and Apache therefore won’t start, if this key requires a passphrase.
    To learn more about each directive, consult the module’s run-time configuration directives reference.
  4. (Optional) Add other default settings as needed, such as default timeout durations. Refer to the module’s run-time configuration directives reference for possibilities.
  5. (Optional) You may want to add logout configuration or better configuration for abbreviated domain names.
  6. (Optional) To enable the use of the module’s per-application configuration directives within .htaccess files and <Directory> and <Location> block directives, adjust your server’s AllowOverride setting to AuthConfig or All
  7. (Optional) The module uses the ServerAdmin address when reporting errors to users. Define an appropriate contact for problem reports.
  8. Save the changes to your httpd.conf file.

Start Apache

Okay, now things get exciting. If everything has gone smoothly so far, you should be able to start Apache. Give it a try, making sure to start your SSL-enabled server. For example:
$ /path/to/apache/bin/apachectl startssl
Notes:
  • If you use Apache’s apachectl script to start Apache, you might run apachectl configtest to do a configuration file syntax test before starting Apache. Often this catches simple mistakes and typos.
  • If Apache fails to start, don’t panic. Diagnostic messages may be sent to the console or more likely to your Apache error_log file. Before you ask someone for help, review the error messages for hints about what went wrong.
  • If Apache fails to start and your error_log says “security_init: couldn't parse session key“, then your RSA private key represented by PubcookieSessionKeyFile is probably encrypted. The module won’t initialize and therefore Apache won’t start if this key requires a passphrase.
Refer to the Troubleshooting section below for further help if Apache fails to start.

Test Pubcookie Authentication

  1. Create a new directory within your DocumentRoot. For example:
    $ cd /var/www/html
    $ mkdir testapp
    $ cd testapp
  2. In this directory, create a new Web page:
    $ pico index.html
    Add a simple message to the file such as “Hello pubcookie-protected world!” and save it.
  3. Create a .htaccess file:
    $ pico .htaccess
  4. Add the following directives to the .htaccess file:
    AuthType EGNetID
    require valid-user
    Substitute the appropriate argument for the AuthType directive, based on the authentication type defined with the PubcookieAuthTypeNames directive in httpd.conf. Note that using these directives in the .htaccess file context requires the AllowOverride AuthConfig setting.
  5. 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.
  6. 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!Note: the module provides an authentication mechanism very similar to Apache’s “basic” access control functionality. You can therefore expect some of the same results: namely, that the module sets the REMOTE_USER and AUTH_TYPE environmet variables, and also logs the userid in your access_log.
  7. Refer to the Troubleshooting section below if this test was unsuccessful.

Logout Configuration and Use

The PubcookieEndSession directive causes the module to clear the current session cookie. Therefore, it can be used to implement application logout. Logout can be configured on a per-application basis using .htaccess or centrally using a virtual logout URI that any application on the server can use. To configure logout using .htaccess: The simplest way to configure logout for an application or static website is to place a .htaccess file in a subdirectory (e.g. logout) and put a PubcookieEndSession in the .htaccess file. It might be laid out something like this:
$ ls -a
.htaccess    images/    index.php    other.php    logout/
$ more .htaccess
PubcookieAppID testapp
Authtype EGNetID
require valid-user
$ more logout/.htaccess
PubcookieEndSession redirect
Then a link from any page to the subdirectory will steer users to logout, allowing PubcookieEndSession to do its work.
<a href="logout/">Logout</a>
To configure and use a matching logout URI: This is a nice alternative for system administrators and application deployers who prefer not to use subdirectories and .htaccess files to configure logout. Essentially, by using Apache’s LocationMatch directive you can create a server-wide matching string that causes the module to invoke PubcookieEndSession without the use of .htaccess. Simply by creating a link with the same string in it, an application can implement logout. Here’s example httpd.conf configuration which defines two such strings, LOGOUT-REDIRECT and LOGOUT-CLEARLOGIN, corresponding with two styles of application logout provided by Pubcookie.
<IfDefine HAVE_SSL>
<IfModule mod_pubcookie.c>

#
# Pubcookie configuration section
#

...

#
# Pubcookie logout configuration
#

<LocationMatch .*/LOGOUT-REDIRECT.*>
AuthType EGNetID
require valid-user
PubcookieEndSession redirect
</LocationMatch>

<LocationMatch .*/LOGOUT-CLEARLOGIN.*>
AuthType EGNetID
require valid-user
PubcookieEndSession clearLogin
</LocationMatch>

</IfModule mod_pubcookie.c>
</IfDefine>
With these directives in place, and the server restarted, any Pubcookie-protected application or static website on the server can create a logout function simply by linking to one of these virtual URIs. For example:
<a href="LOGOUT-REDIRECT">Logout</a>

Cross-Domain Relay Configuration

Authentication across DNS domains was greatly simplified in Pubcookie 3.2.0 with the addition of the POST-based PubcookieLoginMethod.

Virtual Host Configuration

One approach to configuring separate virtual hosts on the same system is to use your main server configuration section to establish default settings for Pubcookie, as described in the Configuration section above. Then override directives as needed for each virtual host. For example, a separate session keypair should be used for each virtual host, which you can do by defining different PubcookieSessionKeyFile and PubcookieSessionCertFile directives within your virtual host configuration. It may be acceptable to use defaults for the module’s other configuration settings. To request a symmetric encryption key for each virtual server name, you can use your current config file to define default values and then override them using command-line options for each virtual host’s SSL private key and certificate files. For example:
$ ./keyclient -k vhost.key -c vhost.crt
Set crypt key for vhost.example.edu
You can also set up a config file for each virtual host and use the keyclient’s -f filename to point to each separately.

Clustered Host Configuration

System administrators frequently cluster together several hosts for better redundancy, performance, stability, and recoverability. Each host in the cluster is configured the same, so each has a SSL certificate and private key identical to the other cluster members. For instance, a site might have 15 webmail servers named webmail1.example.edu through webmail15.example.edu with 15 unique IP addresses. As cluster peers, they’re each equipped with the same SSL keypair for webmail.example.edu. A load-based DNS rotary or Cisco Load Director might control the IP address for the webmail.example.edu name itself. To support such a cluster, use keyclient on one host, say webmail1.example.edu, to generate a webmail.example.edu host key. Then use keyclient -d on all other webmail hosts to download the existing host key to the remaining servers. This way, they all use the same key.

Wildcard Subdomain Key Configuration

Wildcard subdomain configuration allows the module to reuse a single host key file for protecting several server names in the same subdomain. For example, it allows a single students.example.edu host key to function as the encryption key for all the individual student web sites (abe.students.example.edubess.students.example.eduspud.example.edu, etc.) as might happen on a large multi-user web-hosting environment. It works like this: the actual key for AES encryption is a randomly chosen 128 bits from the host key file. To allow the same host key file to encrypt cookies for all subdomains the wildcard-subdomain encryption mode augments the usual 128 bits with the requested web site’s full domain name. The key becomes SHA1( (128 bits from file) + (web site’s full domain name) ). When the module fails to find a key for the requested web site’s full domain name, it will look again with the first part of the name removed, i.e. for a key representing a wildcard for the subdomain. This feature is enabled by setting the PubcookieEncryption directive to AES+DOMAIN and requires that Apache’s UseCanonicalName directive is turned off.

Troubleshooting

To troubleshoot problems with keyclient, review the error messages it produces. If need be, ask your keyserver administrator to review syslog for keyserver error messages corresponding with your keyclient connections. To troubleshoot problems with the module, first look in the Apache error_log. If need be you can log additional debug statements by setting the LogLevel to debug in your httpd.conf file.

Appendix A: How to Enable SSL

Note: This is just an overview; you’ll have to look elsewhere for specific instructions if you need them. (The INSTALL file that comes with mod_ssl is particularly good.)
  1. Build and install OpenSSL.
  2. Build and install Apache from source and add SSL support by following the directions accompanying the mod_ssl package. You will have to decide whether to build modules dynamically or statically. If you use apxs (the Apache DSO module builder), be sure to link it with OpenSSL.
  3. Generate a RSA private key and certificate signing request (CSR) to obtain a signed SSL server certificate. Install the private key and server certificate as directed by the mod_ssl documentation.Note: You may end up reusing this keypair with the keyclient utility, in which case your certificate should be issued by a Certificate Authority trusted by your keyserver. And your private key should be readable without having to enter a passphrase to decrypt it.
  4. Verify that Apache responds to HTTPS requests. SSL should be working before you proceed to build and install the module.

Appendix B: 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.

How Pubcookie Works

0
This overview describes how Pubcookie works at version 3.0.Included on this page:

Components & Roles

The Pubcookie model of user authentication is based on: a User-Agent, Pubcookie’s two server components, and an external authentication service. Servers are classified as “login” or “application” servers. Examples of external authentication services include Kerberos, LDAP, and NIS. The User-Agent is most often represented by a user’s web browser. pubcookie-components How Pubcookie Works The role of the Pubcookie login server is that of the trusted, central authentication service. It interacts directly with users. It verifies usernames and passwords with backend authentication services. It issues cookies to users to provide single sign-on functionality and to application servers to provide authentication information. The role of the Pubcookie application server is that of authentication enforcer. It redirects users who haven’t been authenticated to the login server. It verifies authentication information returned from the login server. It issues cookies to users to maintain authenticated application sessions and provides user authentication information to applications. The role of the external authentication service is to verify user authentication information sent to it from the login server. The role of the User-Agent in all of this is simply to play along: to carry the user to the login server when redirected to do so, to assist the user by rendering the HTML-based user interface of the login server, and to accept all valid cookies set by the login and application servers.

Setup & Configuration

Pubcookie-based authentication begins with the setup and configuration of a Pubcookie login server and at least one Pubcookie application server that hosts at least one Pubcookie-protected application. During the setup phase, the login server and application server negotiate a shared, symmetric key, and the login server’s public key is copied to the application server. Additionally, each application server is configured with the location of its login server and other site-specific details. The User-Agent requires no setup. Standard browser configurations work well.

Initial Sign-on Process

The intial sign-on process (i.e. how a user is initially authenticated) is illustrated in the following diagram; each step is explained in detail below the diagram. Redirection between servers is represented with dashed horizontal lines. pubcookie-iso-diagram How Pubcookie Works
  1. A user makes a request to an application server for a resource (a URL) tied to an application that uses Pubcookie for authentication.
  2. The Pubcookie module intercepts the request and inspects it to determine that the request is not associated with a valid, existing authenticated session for the application and does not carry information from the login server (known as a “granting cookie”, see steps 8 and 9) necessary to establish a new session.The Pubcookie module generates a response, including a “redirect” page and two cookies: a “pre-session” cookie scoped to the application, and a “granting request” cookie scoped to reach the login server. Both cookies contain, among other things, a random number generated by the Pubcookie module.
  3. The “redirect” page causes the user’s browser to make a request to the Pubcookie login server, including the “granting request” cookie.This is the “granting request”. It contains information about the application server, the original resource (URL), the desired type of authentication, etc.
  4. The Pubcookie login server decodes the “granting request” cookie and interprets the contents. In response, it generates a login form page and sends it to the browser, prompting the user to enter username and password.
  5. The user enters his or her username and password into the form and submits it, causing the browser to send the data to the login server.
  6. The Pubcookie login server takes the username and password and sends them to its backend authentication service for verification.
  7. The Pubcookie server receives the verification response.
  8. If verification is successful, the Pubcookie login server generates a response, including a “redirect” page and two new cookies. (If verification fails, another login form page is sent to the user’s browser.) One cookie, known as the “granting cookie”, contains the authenticated username and some other items, including the random number it received from the application server via the “granting request”. The “granting coookie” is protected from tampering by being signed using the private key of the login server, and protected from disclosure by being encrypted using the symmetric key shared by the application server and the login server. It is scoped to reach the application server. The second cookie, known as the “login cookie”, is scoped to the login server and will be used on any subsequent visits by the user to the login server.
  9. The “redirect” page causes the user’s browser to re-request the original resource (URL) on the application server. This request contains the granting cookie set by the login server and the “pre-session” cookie set earlier by the application server.
  10. The Pubcookie module on the application server again intercepts the request, as in step 2. This time it finds the “granting cookie” which it decrypts using the shared symmetric key. It then verifies the signature using the login server’s public key and matches the random number found in the “granting cookie” with the random number found in the “pre-session” cookie. If verification succeeds, the Pubcookie module supplies the authenticated username to the application along with the rest of the original request. It also generates a valid “session cookie” for subsequent requests by the user to the application. Having successfully authenticated the user, the application can finally send the original resource to the user. The Pubcookie module makes sure that the application’s response is accompanied by the new “session cookie”.

Single Sign-on

If, in step 4, the “granting request” is accompanied by a previously established, valid “login cookie” (as set in step 8), then steps 5, 6, and 7 are skipped, and the login server proceeds to step 8, issuing a “granting cookie” using the username as found in the “login cookie”. This provides the “single sign-on” experience for the user, allowing him or her to request resources tied to other Pubcookie-authenticated resources without having to re-enter a password as long as the “login cooke” is still valid (e.g. for 8 hours after the intial sign-on).

Logging Out

A user’s best, most effective method of logging out supercedes that which is provided by Pubcookie itself. Specifically, if a user quits his or her User-Agent or logs out of his or her operating system, all open sessions maintained by Pubcookie will be closed. The underlying assumption is that these user-driven events always clear the cookies that Pubcookie uses to maintain state. However, on some platforms and in some circumstances (see known problems) this assumption is not valid, and other means of logging out must be made. Pubcookie supports its own logout functionality too. Each application can configure a specific resource (URL) that, when requested by a user, will clear the application’s current “session” cookie. Each application can also configure how it wants to respond to such logout requests. It can produce its own response or it can redirect the user to the login server which will generate a custom logout message on the application’s behalf. The latter method provides better consistency among applications and a single point of convergence, at the login server, for other edifying messages, such as the state of the user’s single sign-on session with the login service itself. Therefore, Pubcookie’s logout functionality works on a “per-application” basis not a comprehensive “global” basis. Using this method, a user must manually log out of each application plus the login server. It’s much simpler to quit the browser.

Key Management

Pubcookie’s security model accounts for certain kinds of “man in the middle” attacks. In order to do so, it uses a shared symmetric key to encrypt certain messages sent between each application server and the login server. New keys are generated by the Pubcookie “keyserver” application running on a site’s login server. They are negotiated and distrubuted using the Pubcookie “keyclient” utility during the setup phase of each application server. Keys are then maintained by the Pubcookie “keyserver” application running on a site’s login server. Keys can be revoked at the login server, but automated expiration and renewal processes are not yet provided.

Revision History:

  • 2002/05/01 – original draft [RL Bob]
  • 2002/05/24 – made diagram image [Wallenius]
  • 2002/05/24 – various edits to align with diagram; add headings [Dors]
  • 2002/05/31 – more edits; turned into Web page [Dors]
  • 2002/07/31 – added setup, config, roles [Dors]
  • 2002/08/01 – another pass-thru of edits; random number stuff added [Dors]
  • 2002/08/04 – logout and key management added; new diagrams [Dors]
  • 2002/08/13 – clarified logout assumptions [Dors]

Login Server Administration Guide

0
Application server administrators

Overview

This guide helps site administrators run a Pubcookie login server. Everything from setup and configuration to integration and customization is covered below. Application server administrators should refer to the Pubcookie Apache module guide or ISAPI filter guide for instructions on deploying a Pubcookie application server which authenticates using your local login server.

What’s New

Significant improvements and changes to the login server components included in Pubcookie 3.3.4:
  • Added support for 4096-bit private keys to login cgi.
  • Modified login cgi to log user’s IP address on Redirect log line.
Significant improvements and changes to the login server components included in Pubcookie 3.3.2d:
  • Applied security fixes to address vulnerability described in June 28, 2007 security advisory.
Significant improvements and changes to the login server components included in Pubcookie 3.3.2c:
  • Fixed strlcpy.c bug. Pubcookie’s implementation of strlcpy.c had a null termination bug when the source string (length – 1) exactly fits the destination string buffer.
  • Fixed Javascript call in login cgi when posting data back to the application server. Added ‘()’ to document.query.submit.
Significant improvements and changes to the login server components included in Pubcookie 3.3.2:
  • Added LDAPS support to LDAP verifier. Enable it with new ldap_tls config file variable. Configure TLS authentication with new ldap_key_fileldap_cert_file, and ldap_ca_file variables.
  • Fixed a bug to avoid a possible loop condition with unexpired PBC_CLEAR_COOKIE cookies.
Significant improvements and changes to the login server components included in Pubcookie 3.3.1:
  • New default login CGI templates with more standard XHTML, CSS, and utf-8 encoding.
  • Added clear_username_at_logout site policy to login cgi to control whether the username is cleared on logout.
  • Modified session reauthentication messaging. The login cgi now includes in the granting message whether or not it handled a reauthentication request.
  • Fixed null pointer usage in LDAP verifier when version is empty.
  • Modified login cgi to use more consistent audit logging strings. Prepended the “first kiss” timestamp to authentication success and failure log file messages.
  • Modified login cgi to allow ‘http:’ and ‘https:’ in app server uri query strings without percent encoding the colon.
Significant improvements and changes to the login server components included in Pubcookie 3.3.0a:
  • Applied security fixes to address vulnerabilities described in March 6, 2006 security advisory.
  • Fixed problems found in 3.3.0 release with “getcred” flavor’s Kerberos ticket passing.
Significant improvements and changes to the login server components included in Pubcookie 3.3.0:
  • Added AES encryption support. The login cgi will encrypt authentication messages with the encryption algorithm specified in the authentication request.
  • Changed login cgi to use AES encryption on its private login cookies.
  • Added PUBCOOKIE_LOGIN_CONFIG_FILE environment variable for defining an alternate config file for the login cgi.
  • Added support for the Apache module’s wildcard subdomain key encryption mode for large multi-user web-hosting environments.
  • Added kerberos5_extralife config file variable to extend the lifetime of delegated tickets past the SSO lifetime.
  • Added lowercase_username and uppercase_username site policies to the login cgi for modifying the case of the username.
  • Modified minimum LDAP_VENDOR_VERSION in configure script for better compatibility with Sun LDAP SDK.
  • Better handling of stray, malicious, and other spurious cookies. The login cgi will read all available login cookies to find a valid one. Previously, it only checked the first one, which might be invalid.
  • Other minor login cgi fixes to error handling and cookie clearing.
See doc/CHANGES.txt for bug fixes and other improvements.

Upgrading & Compatibility

In general, the login server components can be upgraded (built and installed) on a live system while safely maintaining your existing configuration file (PREFIX/config) and login templates (PREFIX/login_templates). Running make install on such a system will do the following:
  • install new keyserver, keyclient, and login cgi binaries into PREFIX/keyserverPREFIX/keyclient, and PREFIX/login/index.cgi, respectively.
  • install a set of (possibly updated) generic login templates is installed into PREFIX/login_templates.default but not into PREFIX/login_templates if it already exists.
  • install a new sample configuration file (PREFIX/config.login.sample).
Sites should compare their current config file and current templates against the new ones and resolve significant differences before copying the new login cgi and other binaries in production locations. Here are some additional compatibility notes for upgrading between specific versions:
Upgrading to 3.3.4:
User’s IP address added to Redirect log line: Sites that parse the login cgi’s log file data should be aware that the user’s IP address has been added to support additional business purposes (e.g. usage metrics, forensics, troubleshooting). Any scripts or programs that depend on the format of this data should be tested for compatibility prior to deploying the new version.
Upgrading to 3.3:
AES encryption impact on SSO: Sites upgrading to 3.3 should be aware that in version 3.3 the login cgi uses AES encryption on all login cookies, while earlier versions have used DES encryption. As a result, login cookies obtained by users prior to upgrading the login cgi will be invalid after the upgrade. This will affect some users’ SSO experience in the following ways: first, after the upgrade some users will have to reauthenticate where they might not have had to before; others might notice that the login page no longer remembers (i.e. no longer pre-fills) their username. Again, this is only around the time of the upgrade and only for browsing sessions that were started before the upgrade occurs.
Upgrading from version 3.2 to 3.3:
Template changes: The only template changes between versions 3.2 and 3.3 are those from the February 2006 login server security patch release. Therefore, sites upgrading an unpatched 3.2 login server (3.2.1a or earlier) to a patched 3.3 login server (3.3.0a or higher) should update their templates accordingly. Namely, explicit Content-Type definitions have been added to the following templates: errorloginnonpost_redirectnotokstatuspinit_response1, and logout_part1. Also, the entire HTML comment containing an unnecessary %url% variable substitution was removed from the nonpost_redirecttemplate. These files can all be found in PREFIX/login_templates.default.Sites upgrading to 3.3 from the patched 3.2.1b release or from a manually patched 3.2 version should already have these template changes as they are part of the patch.
Upgrading from version 3.0/3.1 to 3.3:
Template changes: Sites upgrading from 3.0/3.1 to version 3.3 must update their templates to account for changes that were introduced in versions 3.2 and carried into 3.3, as well as for those from the February 2006 login server security patch release. As noted above, the patch release updated to the following templates: errorloginnonpost_redirectnotokstatuspinit_response1, and logout_part1. These changes are on top of those from version 3.2, which introduced new variable substitutions in several templates. Sites should identify these substitutions by comparing these templates relative to their own production templates:
  • login (adds new %reason% and %version% variables)
  • form_expired (adds new %time variable)
  • logout_part2 (adds new %version% variable)
  • pinit_response2 (adds new %version% variable)
The following templates are new (in version 3.2, and therefore in 3.3) and should be reviewed and added to your production templates:
  • notoknotok_badagentnotok_form_multipartnotok_genericnotok_need_ssl
Finally, the following templates have been removed (in version 3.2, and therefore in 3.3) and therefore can be removed from your production template directory after upgrading:
  • notok_part1notok_part2
Compatibility note on version 3.1 relays:
Third-party relays deprecated: The need for the cgi-based relays introduced in version 3.1 to authenticate across DNS domains was redressed by the POST-based messaging method introduced in version 3.2 and, thenceforth, use of third-party 3.1 relays has been deprecated. To continue to support third-party relays at all, you must use the --enable-unsafe-relay configure option while building the login cgi. Preferably, upgrade all your application servers using third-party relays to version 3.2 or higher, and configure them to use the POST-based messaging method. Then there will be no need to support third-party relays in your login cgi.

System Components

The Pubcookie login server really consists of two separate components with separate purposes:
login server cgi
The Pubcookie login server uses a CGI program to handle browser requests. This CGI program, hereafter referred to as the login cgi or index.cgi, is compiled from C and is a site’s central Pubcookie component. End-users rely on it to authenticate; application servers rely on it for authentication assertions. The login cgi is typically powered by Apache HTTP Server software.
keyserver
The Pubcookie login server uses the keyserver component to generate and distribute symmetric encryption keys for participating servers, including your Pubcookie login server and all application servers. The keyserver runs as a service under inetd or xinetd.

Basic Login Flavor

The login cgi supports an abstraction called a login flavor. A login flavor encapsulates a specific set of functionality and features that influence how and when end-user authentication takes place. The distribution comes with one login flavor called the basic login flavor. This login flavor has a rich feature set, including single sign-on (SSO) user authentication, a pluggable backend authentication service interface, kiosk mode, and much more. This guide might, in fact, be described as a guide to the basic login flavor, it is so tailored to its installation and use.

Authentication Types

What the login cgi calls a login flavor, the application server components call an authentication type. The naming is rooted in Apache’s AuthType directive and it’s somewhat regrettable since they aren’t quite the same thing. For now it’s probably enough to say that, unless you build another login flavor, most application servers will be configured with a single choice of Pubcookie authentication types, one corresponding directly with the basic login flavor. How primary authentication takes place (that is, how usernames and passwords are actually authenticated) depends on how the basic login flavor verifies credentials with your backend authentication service.

Verifiers & Authentication Services

The basic login flavor performs username-and-password credential verification through a simple pluggable interface to backend authentication services. These plug-ins are called verifiers and the distribution comes with several:
kerberos_v5
verifies credentials using a Kerberos 5 KDC
ldap
verifies credentials using an LDAP server
shadow
verifies credentials using /etc/shadow
fork
verifies credentials using custom forked program
alwaystrue
verifies all credentials as successful. good for testing.
Compile-time decisions and run-time configuration determines which verifier is used by basic login flavor.

More About Abstractions

These login cgi abstractions help applications to remain independent of the method, or methods, used by the login server to authenticate user credentials. For example, a site might migrate from LDAP-based authentication to Kerberos authentication. It’s attractive to hide the transition from applications. Here applications would continue to use their institutional “netid” authentication type, corresponding with their site’s basic login flavor, while the login server administrators transition, transparently, from one verifier to another. Other sites may want to be able to choose from different backend authentication services. For example, the University of Washington uses the basic login flavor along side and a more secure flavor that uses SecurID in addition to username and password for primary authentication. Applications choose which flavor they want by configuring the appropriate authentication type.

Building Components

The configure script included in the distribution helps you build and install the login cgi and keyserver according to your platform and individual preferences. To build and install a barebones login server for evaluation and testing, run the following commands:
$ ./configure --enable-login --disable-apache
$ make
$ make install
This builds the login cgi with support for the basic flavor and the “alwaystrue” verifier. It also builds the keyserver and keyclient binaries. Files are installed, and directories created, according to the default installation directory prefix, henceforth called PREFIX, which defaults to /usr/local/pubcookie. Use the --prefix configure option to define an alternative location. Review the results by listing the installation PREFIX directory contents.
$ ls
total 240
-rw-r--r--  root  root    935 config                    # config file
-rw-r--r--  root  root    935 config.login.sample       # sample config
-rwxr-xr-x  root  root  92229 keyclient*                # keyclient
drwxr-xr-x  root  root   4096 keys/                     # keystore
-rwxr-xr-x  root  root  92929 keyserver*                # keyserver
drwxr-xr-x  root  root   4096 login/                    # login cgi dir
drwxr-xr-x  root  root   4096 login_templates/          # templates
drwxr-xr-x  root  root   4096 login_templates.default/  # originals
-rw-r--r--  root  root   2048 starter.key               # starter key

$ ls login
total 204
drwxr-xr-x  root  root   4096 images/                   # images
-rwxr-xr-x  root  root  99299 index.cgi*                # login cgi
Note: initial file permissions assigned by the installation process may not be acceptable for production use. Please refer to Appendix B: Permissions & Security section for a discussion of this subject. Continue through the setup and configration instructions using the alwaystrue verifier. After you’ve gained some familiarity with a working system, you can rebuild the login cgi to use a different verifier that goes against your local authentication service. Review the configure help for the build options.
$ ./configure --help
Refer also to the Kerberos, LDAP, and FastCGI configuration sections.

SSL & Granting Key Pairs

SSL key pairs have several functions in the operation of a Pubcookie login server. One key pair may suffice for all of them, but two key pairs often works better in practice. SSL key pair: The SSL private key and certificate used to SSL-enable Apache can be reused for the first keypair. This key pair is particularly suited for use with the keyclient and keyserver because the SSL public key certificate most likely has been signed and issued by a trusted Certificate Authority. The login cgi also uses this key pair, but only for signing and verifying “login” cookies. Note: the login cgi and keyserver cannot read encrypted RSA private keys because they can’t prompt for the passphrase. To reuse an encrypted SSL key, you’ll first have to remove the passphrase. Refer to Appendix C: OpenSSL Commands for help. The ssl_key_file and ssl_cert_file config file variables will point to these keys. Granting key pair: A second key pair is used to sign and verify “granting” cookies, the authentication assertions generated and signed by the login cgi and verified by application servers. Here the certificate issuer isn’t important, but the SSL public key certificate must be distributed to other servers. Therefore, a separate “granting” key pair is often used. Refer to Appendix C: OpenSSL Commands if you need help generating this key pair. The granting_cert_file and granting_key_file config file variables will point to these keys. Note: the key pairs described in this section (used for SSL and message signing primarily) are in addition to the symmetric encryption keys Pubcookie uses for data encryption.

Run-Time Config File Setup

The login cgi and keyserver read configuration settings from a run-time configuration file. The default location, PREFIX/config, is compiled in by default. The login cgi will use an alternate config file if a PUBCOOKIE_LOGIN_CONFIG_FILE environment variable defines one. This is useful when more than one logical login server is running on the same machine (using virutal hosts in Apache). The keyserver will use an alternate config file if the -f <filename> command-line option defines one. The config file format is one variable name-value pair per line, except where a trailing backslash  character continues a value to the next line. A sample config file appropriate for a login server is provided (see PREFIX/config or PREFIX/config.login.sample if you’re upgrading) as a starting point. It will look something like this:
# 1 is a good starting point
logging_level: 1

# the credential verifier used by the basic flavor
basic_verifier: alwaystrue

# SSL session keypair
ssl_key_file: /etc/httpd/conf/ssl.key/server.key
ssl_cert_file: /etc/httpd/conf/ssl.crt/server.crt

# granting keypair
granting_key_file: /usr/local/pubcookie/keys/pubcookie_granting.key
granting_cert_file: /usr/local/pubcookie/keys/pubcookie_granting.cert 

# login server config
login_uri: https://login.example.edu/
login_host: login.example.edu
enterprise_domain: .example.edu
logout_prog: /logout/index.cgi

# keyserver config
keymgt_uri: https://login.example.edu:2222
keyserver_client_list: login.example.edu trusted.example.edu
ssl_ca_file: /etc/httpd/conf/ssl.crt/ca-bundle.crt

# site-specific policies
default_l_expire: 8h
Begin editing your config file, using the config file variable reference as needed for examples and descriptions. Notes:
  • See how several variables in the example above are derived from the login server name, login.example.edu. This will be true for your config file too.
  • The example login server appears to be reusing its SSL key pair located in server.key and server.crt.
  • The example login server has a separate “granting” key pair. Refer to Appendix C: OpenSSL Commands if you need help generating this key pair.
  • The example keyserver appears to be using a file bundle of trusted Certificate Authorities (i.e., ca-bundle.crt). This file must contain all the trusted CA root certificates the site is using to verify keyclient certificates.

Keyserver Setup

Keyserver is designed to run as a service under inetd or xinetd. If you use inetd, add a line like the following to /etc/inetd.conf:
2222  stream  tcp  nowait  root  /usr/local/pubcookie/keyserver keyserver
If you use xinetd, create /etc/xinetd.d/keyserver with the following contents:
# description: pubcookie keyserver
service keyserver
{
	type			= UNLISTED
	protocol		= tcp
	port			= 2222
	disable			= no
	socket_type		= stream
	wait			= no
	user			= root
	group			= tty
	server			= /usr/local/pubcookie/keyserver
}
After adding the line to inetd.conf, or the file to xinetd, restart your inetd or xinetd service. Note: keyserver requires ssl_key_file and ssl_cert_file, and either ssl_ca_file or ssl_ca_path depending on how you handle trusted root CA certificates. Keyserver also uses granting_cert_file for distributing your “granting” certificate. And if you want control over which hosts can request keys, you can do so by defining a keyserver_client_list for authorizing new hosts.

Key Management Methodology

This section describes how symmetric encryption keys are managed by the Pubcookie keyserver. It issues keys to all participating servers, including all login servers and application servers. The keystore: A master copy of each 2048-byte host key is stored on the login server in its keystore, PREFIX/keys, in a filename based on the server’s SSL certificate’s Common Name. For example, a site with a login server and three application servers might have a keystore like this:
$ ls /usr/local/pubcookie/keys
total 204
-rw-r--r--  root  root   2048 weblogin.example.edu
-rw-r--r--  root  root   2048 appserver.example.edu
-rw-r--r--  root  root   2048 mail.example.edu
-rw-r--r--  root  root   2048 my.example.edu
-rw-r--r--  root  root    887 pubcookie_granting.key
-rw-r--r--  root  root   1224 pubcookie_granting.cert
Each host key can be used for DES encryption or AES encryption. The login cgi (as of version 3.3) uses AES encryption for login cookies. It uses either AES or DES for granting cookies, depending on the algorithm specified by the application server in its authentication request. New key generation: New host keys are generated and issued by the keyserver upon request. Running keyclient on a host initiates the request. If the keyclient host is authorized, and the keyclient and keyserver trust each other, the request is fulfilled. New keyclient host authorization: If the keyserver_client_list config variable is set, keyserver performs authorization on all keyclient requests. If it is not set, keyserver will issue host keys to any trusted keyclient. When authorization is enabled, grant-or-deny decisions are based on the presence a host in the keystore. If keyserver finds a host in the keystore, then that host can request a key. This seems like a catch-22: to create a new host key in the keystore, the key must already exist in the keystore. But it’s not: site administrators can use the keyclient’s “permit” option to authorize new servers to request host keys. For example:
$ keyclient -P new.example.edu
Host new.example.edu is permitted
This can be done manually by the login server administrator or by some kind of automated web-based registration service. The keyserver_client_list defines which hosts are authorized to use the permit option, allowing you to authorize new hosts without necessarily having to log in to the login server to do so. Trust: SSL/TLS mutual authentication Pubcookie uses elements of Public-Key Infrastructure (PKI) and SSL/TLS for mutual server authentication and data privacy between keyclient and keyserver. Trust is anchored by the Certificate Authorities used to sign, issue, and verify the certificates exchanged during keyclient connections. Mutual authentication means the keyclient and keyserver must identify each other. The keyclient must verify the SSL certificate presented by the keyserver. Likewise, the keyserver must verify the SSL certificates presented by keyclients. To do so, they both require trusted CA root certificates to do the verification. This is configured via ssl_ca_file or ssl_ca_path, which might point to your own institutional CA root certificate or pehaps the CA root certificate bundle that comes with OpenSSL, whatever you happen to be basing your trust policy on. Working with untrusted keyclients: An untrusted keyclient is one using a SSL certificate signed by a Certificate Authority the keyserver doesn’t trust. To allow such keyclients to request host keys without having to obtain another certificate, there’s a workaround. The login server administrator can cache the keyclient’s SSL certificate (public key) in the keystore. The keyserver can then use the public key itself to verify the keyclient. As a result, an otherwise untrusted keyclient can request host keys without changing the overall CA trust policy and configuration. Note: the keyclient’s -U cert_file option will upload a certificate to the keyserver, e.g.:
$ ./keyclient -U untrusted.example.edu.crt
This command can only be run from a trusted host, i.e. in the keyserver_client_list list.

Run Keyclient For Login Server

To generate a symmetric encryption key for your login server, copy the starter key found in the distribution into your keystore. Use your login_host name for the filename. For example:
$ cd /usr/local/pubcookie
$ cp starter.key keys/login.example.edu
The starter key allows keyserver to initialize when the keystore would otherwise be empty. Now you should be able to run keyclient to request a new host key for the login server based on your current config file settings:
$ ./keyclient
Set crypt key for login.example.edu
Note: if keyclient is unable to set a new host key, look in syslog for keyserver error messages.

Deploying Login CGI

The login cgi doesn’t depend on its own filename or location, so your primary concern in deploying it should be to create a simple URL that’s easy for users to recognize and trust with their password. The most common approach is to copy it from PREFIX/login/index.cgi to your Apache server’s root directory, resulting in a URL such as https://weblogin.example.edu/. The default HTML templates use relative links to locate the default stylesheet and inline images. These files are found in a media subdirectory. Copy the PREFIX/login/media directory to the same location as the login cgi. It should include one stylesheet file and three GIF images. Refer to Appendix A: Apache Configuration if you’re unfamiliar with the directives that control how Apache detects and handles cgi scripts, particularly as a directory index like index.cgi.

Testing Login CGI

The login cgi can be opened directly in a browser. This is sometimes called a pinit (for Pubcookie init, like kinit) since authentication is requested without being tied to an application. It’s a good way to test your current config file and verifier. Go ahead and try it now. The login page you see comes from the PREFIX/login_templates/login and PREFIX/login_templates/login_pinit templates. If authentication succeeds, congratulations, you now can deploy an application server using the Pubcookie Apache module or Pubcookie ISAPI Filter to test the components together. Then you can go on to build and configure another verifier that goes against your authentication service and customize the login cgi templates for your site. If authentication fails, don’t panic, look in your syslog for error messages from the login cgi and refer to the Logging & Debugging section for further advice.

Logging & Debugging

The login cgi uses syslog to log all messages. Logging can be configured using the logging_level variable. A value of 1 gets you basic audit activity such as logins and redirects which is most likely sufficient for normal operation. When additional debugging information is needed increase the value to 3. The keyserver also uses syslog and tends to log all critical error messages. Keyclient uses standard output for its messages.

Login CGI Templates

The login cgi reads HTML templates from the PREFIX/login_templates directory in order to create login, logout, error, and redirect pages. The login cgi will read from an alternative location if the template_root config file variable is defined. A set of generic, sample templates is copied into place during initial installation. A backup set is also copied to PREFIX/login_templates.default. Edit these templates (which represent “Example University”) to brand the login server for your organization and to meet local web design standards. Refer to the login cgi template reference for descriptions of each template.

Custom Login Messages

This is all about branding. Some application owners require branding of the login page with their own login prompt text and icons. The login cgi support this capability through the use of custom login message templates (small HTML snippets) configured on the login server. They can’t take over the entire design of the login page, but it does provide a place for friendlier, custom messages. A custom login message applies to a single application, so the corresponding template is stored in a file according to the server name and application id. The file path is based on the custom_login_message_dirconfiguration variable (the directory containing all the custom login message templates, which defaults to the same directory as all the other login templates). The filename is based on thecustom_login_file_prefix configuration variable (the filename prefix for all custom login message templates) plus the server name and application id. For example, to configure a custom login message for an application on appserver.example.edu with an application id of testapp, you would place the custom message (HTML snippet) in the following file (based on default values, of course):
PREFIX/login_templates/custom_login_msg-appserver.example.ed-testapp
You can see where custom login messages are positioned relative to other elements on the login page by viewing the HTML source of the login template. They come just before the reason the user has to authenticate.

Browser Acceptance Configuration

The optional PREFIX/ok_browsers file contains a list of browsers accepted by the login cgi. This file provides a way to block browsers that either have a known security flaw (i.e., don’t forget cookies when they should) or don’t work with Pubcookie. The ok_browsers file is optional.

Logout Configuration

The login cgi handles logout requests initiated by, and redirected from, applications configured with Pubcookie’s per-application logout functionality. Handling these logout requests is built in; no configuration is necessary to the login cgi itself. However, through additional configuration you can create a separate, direct logout URL for your login server (e.g. https://weblogin.example.edu/logout). You can also tailor the logout response messages for your favorite applications. Those are the two subjects of this section. Note: Pubcookie does not support “global” logout, that is, logout of all sessions, all cookies, all at once. Rather, it supports per-application-session logout with optional ability also to logout of the login server. Therefore, users still must be educated not to leave their browsers open and unattended without proper precautions such as locking their computer and using password-protected screensavers. Exiting the browser remains the best way for users to get logged out of everything at once. Configuring a Direct Logout URI: If you want to provide a URL where users can go directly to clear their single sign-on session (by way of clearning their “login” cookie), it can be created with the logout_prog config variable and a Unix symbolic link. Here’s an example. Suppose the login cgi has been installed in the DocumentRoot directory (e.g. in /var/www/html) with a URL of https://weblogin.example.edu. To create a logout URI of /logout/ just below that, i.e., https://weblogin.example.edu/logout/, you’d do this: Change to the appropriate directory, create the subdirectory, and make the symbolic link to your login cgi:
$ cd /var/www/html
$ mkdir logout
$ cd logout
$ ln -s ../index.cgi index.cgi
Adjust the directory according to the location of your login cgi. Now any request to /logout/ on the server will map to your login cgi. Now add the appropriate logout_prog variable to your config file:
logout_prog: /logout/index.cgi
Customizing Logout Responses For Special Apps: The login cgi builds logout response pages from several templates. One template, logout_app, which is the most specific to each application, can be overridden on a per-application basis, as configured and identified by the originating server name and application id. It requires one app_logout_string config file variable for each application, where the server name and id are tacked on using dashes. For example:
# custom logout msgs
app_logout_string-appserver.example.edu-testapp: 
          <font size="+1">Testapp logout worked just fine.</font>
app_logout_string-webmail.example.edu-webmail: 
          <font size="+1">Webmail Logout Successful!</font>
Note: Since the login cgi reads the config file and its HTML templates on each request, there’s no need to recompile the login cgi in order to modify response messages.

Kiosk Configuration

Use the kiosk variable to apply a site policy for reduced single sign-on duration for identified kiosks. The login cgi supports matching by user-agent string, remote IP address, or IP address ranges. For example:
kiosk:   20m Safari/85.6 
         15m Safari 
         10m ExampleKiosk 140.142.14.39 140.142.21.* 
         1h  140.142.15.10-200
This sets a curiously elaborate, but nonetheless illustrative, kiosk policy: a 20-minute SSO duration for Safari 85.6, a 15-minute SSO for all other versions of Safari, a 10-minute SSO to remote browsers with “ExampleKiosk” in the user-agent string as well as to the remote IP address 140.142.14.39 and the 140.142.21 subdomain, and a one-hour SSO duration for IP addresses in the range 140.142.15.10-200. Matching by user-agent string is particularly useful for applying reduced SSO to managed kiosks that have a locally customized user-agent string such as:
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; ExampleKiosk; Windows NT 5.0)
How to customize user-agent strings is beyond the scope of this guide, but resources and tools, such as the Internet Explorer Administration Kit, do exist to help with this task.

Site Policy Configuration

This section highlights some of the possible site policies you can define in your config file. These options may be overlooked, but they can enhance the user experience and shape the security policy of your login server.
  • Use default_l_expire to define your default single sign-on duration. Primary authentication occurs when user-provided credentials are verified directly. Subsequent authentication is based on checking the “login” cookie. This setting defines how long this cookie is valid.
  • Use form_expire_time to define how long users have to log in. Taking too long will result in a new login form (with the form_expired template message included). The default expiration is 60 seconds.
  • Use static_user_field to define the editability of the userid field during a single browsing session. You may want to allow some flexibility or force users to close the browser before switching between users.
  • Use the retain_username_on_failed_authn to define whether the userid is retained after a failed login attempt. Users will appreciate this if they mistyped their password, not their userid.
  • Use trim_username_to_atsign to define whether users can enter a userid that looks like an email address. Sites that aren’t verifying full Kerberos principals (e.g. joe@example.edu) or userids that look like email addresses can use this feature to provide some flexibility in this regard, i.e., to trim off the extra realm info the user added and verify just the proper userid.
  • Use lowercase_username or uppercase_username to change the userid to lowercase or uppercase.
Refer to the config file variable reference to review these variables and the values they take.

Kerberos 5 Verifier Configuration

To build the login cgi with support for the Kerberos 5 verifier, run the configure script with the Kerberos option enabled:
./configure --enable-login --disable-apache --enable-krb5
If needed, the configure script has other options for adjusting the location of the Kerberos header files and libraries. To configure the login cgi to use the Kerberos verifier, edit your config file and set basic_verifier to kerberos_v5. Additionally, two other config file variables control the Kerberos 5 verifier: kerberos5_service_nameand kerberos5_keytab. For example:
# kerberos verifier config
basic_verifier: kerberos_v5
kerberos5_service_name: pubcookie
kerberos5_keytab: /usr/local/pubcookie/keys/pubcookie.keytab
Enable the append_realm variable if you want the Kerberos authentication realm to be appended to the user name after authentication but before issuing cookies (i.e., target servers will receive user@REALM.) Use the default_realm variable to define a default Kerberos authentication realm to pass to the verifier when none is submitted via the login form. To authenticate responses from your Kerberos server, the login server and Kerberos server must share a service key. You can use an existing service key or generate a new one with the help of your Kerberos administrator. Keep in mind that the keytab file that contains your service key must be readable by the login cgi. Since the login cgi will most likely run as a non-root user, it’s recommended that you use a service key other than the “host” service key typically stored in /etc/krb5.keytab. Similar to user keys, service keys have a principal of the form <service_name>/<hostname>@<realm>. The hostname is the fully qualified hostname for your login server, and the realm is the Kerberos realm. But the service name is what counts most to the Kerberos 5 verifier. Your service name can be set with the kerberos5_service_name variable. Contact your local Kerberos domain administrator if you need help creating a service key, generating a keytab file, or otherwise configuring Kerberos (e.g. /etc/krb5.conf) on your login server. See doc/krb5-getcred.html for details on how to configure and use Kerberos credential passing.

LDAP Verifier Configuration

To build the login cgi with support for the LDAP verifier, run the configure script with the LDAP option enabled:
./configure --enable-login --disable-apache --enable-ldap
Note: Other configure options can help you specify the location of your LDAP header files and libraries. See ./configure --help. To configure the login cgi to use the LDAP verifier, set basic_verifier to ldap in your config file. To configure the LDAP verifier itself, add an ldap_uri to your config file. This variable defines how the verifier connects to your LDAP directory. To enable LDAPS with TLS authentication, configure ldap_tls,ldap_key_fileldap_cert_file, and ldap_ca_file.
# ldap verifier config
basic_verifier: ldap
ldap_uri: ldaps://host/o=searchbase???(uid=%s)?x-BindDN=Bind%20DN,x-Password=Password
Note: LDAP in general is not case sensitive, so most implementations don’t enforce case sensitivity on the username (uid) attribute. This may result in usernames of mixed case being sent to application servers for the same authenticated user (e.g. jon, Jon, jOn). To prevent this, use the lowercase_username site policy to change the username entered to lowercase.

Redundant Login Server Configuration

The login cgi and keyserver can be deployed in a redundant configuration, provided that they share the same cluster name and settings. Use the login_servers variable to configure keyserver to push new host keys to its peers.

FastCGI Configuration

The login cgi can run as a FastCGI process. This allows one or more instances of the login cgi to persist and handle many requests rather than just one. FastCGI support is enabled with the --with-fcgi=<path to fcgi> option. Example Apache configuration follows below; modify as needed.
LoadModule fastcgi_module     libexec/mod_fastcgi.so
FastCgiConfig 
       -appConnTimeout 0 
       -idle-Timeout 30 
       -init-start-delay 2 
       -killInterval 300 
       -listen-Queue-Depth 50 
       -maxProcesses 10 
       -maxClassProcesses 2 
       -minProcesses 1 
       -startDelay 10

Supporting Application Servers

To support application servers, other system administrators will need to know the location of your login server, keyserver, and how trust is handled on your keyserver. That is, which CAs the keyserver trusts to verify keyclient certificates; and which CA can be used by the keyclient to verify your keyserver certificate.

Appendix A: Apache Configuration

The default filename for the login cgi, index.cgi, is a common name for a cgi program that is executed when a directory’s URL is requested. The DirectoryIndex directive defines how Apache handles such requests, typically choosing the first file it finds in its DirectoryIndex list. With appropriate configuration, this can be your login cgi. For example, you might use the follow DirectoryIndex directive:
DirectoryIndex index.cgi index.html
Apache also needs to know how to identify cgi scripts by the .cgi filename extension. Some distributions of Apache have the cgi handler disabled. Make sure the following line is in your httpd.conf and not commented out.
AddHandler cgi-script .cgi
Finally, Apache must allow execution of cgi scripts in the directory where the login cgi is located. If it’s outside of a ScriptAlias directory, you can control this with the Options directive.
Options Indexes FollowSymLinks ExecCGI

Appendix B: Permissions & Security

Due to the important nature of the Pubcookie login server, the only other services that should be run on the same system are those which receive an equally high level of scrutiny for security. Some of the login cgi’s supporting files are sensitive, particularly the two private keys, ssl_key_file and granting_key_file. In a production environment, non-root users shouldn’t be able to read these files. However, in a typical Apache configuration the login cgi runs within a restricted user context defined by the User and Group server directives. They are usually set to some non-privileged user and group (e.g. nobody.nobody). One approach to permissions is simply to make the sensitive files owned and readable by the non-privileged Apache user (nobody.nobody and octal 600700 for the keys directory).
drwx------  nobody nobody   4096 keys/ 
-rw-------  nobody nobody   4096 keys/pubcookie_granting.key
-rw-------  nobody nobody   4096 keys/pubcookie_session.key
Another approach is to run Apache as a non-privileged user but use a group that no users are allowed to be in (e.g. nobody.www where no users are in the www group). Then sensitive files can be restricted to just root and to the empty group (root.www and octal 640750 for the keys directory). Since the login cgi runs in the context of the group, it can read the files it needs to.
drwxr-x---  root   www      4096 keys/ 
-rw-r-----  root   www      4096 keys/pubcookie_granting.key
-rw-r-----  root   www      4096 keys/pubcookie_session.key
Note: since the keyserver is run by inetd or xinetd, it is most likely run as root and therefore can read and write supporting files as needed.

Appendix C: OpenSSL Commands

To generate a new RSA private key and self-signed public key certificate, (for example, for the “granting” key pair), change to the PREFIX/keys directory and use the following OpenSSL command as an example:
$ cd /usr/local/pubcookie/keys
$ openssl req -new -x509 -out pubcookie_granting.cert 
    -newkey rsa:1024 -nodes -keyout pubcookie_granting.key
To remove the pass phrase on an SSL private key:
$ openssl rsa -in server.key -out unencrypted.key
The man pages for x509rsa, and req have many other useful OpenSSL command examples.

Appendix D: Version History

Significant improvements and changes to the login server components included in Pubcookie 3.2.1:
  • Added kerserver support for subjectAltName wildcards.
  • Fixed login cgi to put redirect messages into the normal audit logging stream.
  • Added login_host_cookie_domain to make login cookie domain configurable.
  • Added remote realm, if present, to authentication success message in flavor_basic logging.
  • Fixed LDAP verifier to default to LDAPv3 for all LDAP SDKs and added “x-Version” parameter to the LDAP URL.
  • Revised “fork” verifier to pass username and password via stdin to the forked executable. The config file variable has been changed from fork_exe to verify_exe to avoid accidentally running the wrong executable.
Significant improvements and changes to the login server components included in Pubcookie 3.2.0:
  • Added support for custom per-application login messages
  • Added keyserver support to allow keyclient authentication by wildcard certificates and Subject Alt Names
  • Added keyserver support to allow keyclient certificates signed by untrusted CAs to cache a public key on the keyserver and use it in server authentication
  • Added keyclient -U <certfile> option for admins to upload a public key certificate to the keyserver
  • Added version string to login server template as HTML comment
  • Improved POST-based messaging between application servers and login server
  • Deprecated the use of third-party relay cgi

how to improve laptop gaming performance

0
improve laptop gaming performance
PC gaming is a multi-billion industry, and it’s still growing.  If you’re a game enthusiast, we’ve got a treat for you; we shed more light on how you can optimize your laptop for a fulfilling experience. However, optimizing your hardware is just a piece of the puzzle: games themselves have plenty of hidden potentials that can significantly improve the way they look and feel.   Playing games should not be an exercise of frustration. Read on some of our fantastic tips and learn how you can optimize your laptop.  

1) Update your drivers

  Your graphics card is the centerpiece of your gaming experience and running old drivers is not a good idea If you want the best performance. Going from the driver that came either with your laptop or with your graphics card to the latest version can improve your overall experience significantly. Surprisingly, many of the gamers fail to update their drivers to the newest version.   These days, PCs running on standard OS such as Windows, macOS, and Linux have systems that are based around the same hardware, with the same architecture, and therefore updating your drivers is not a hassle anymore, but a slight inconvenience that has been swallowed up in the standard OS update.   However, when it comes to graphics drivers, it quite challenging since most systems do not offer automatic updates. Therefore, you’ll need to ensure the management software such as Nvidia GeForce or AMD gaming Evolved is set to update automatically.  

2) Tweak-in game settings

  Updating your drivers will get you only so far. Adjusting your game setting allows you to gain frames per second, which makes your laptop games run faster and improve your overall experience. Ideally, you’ll want to run your game at your monitor’s native resolution.   Another game set that is often ignored is the display setting. While adjusting the display setting improves your gaming performance, it may reduce texture quality.   It’s amazing how games provide quite a range of options, and so it’s worth having a closer look at the custom video setting in each game before playing. You can experiment with the settings and see what works best for your system. Aim to strike a balance between how the game looks and how it plays on the network. optimum-video-settings-for-games how to improve laptop gaming performance

3) Disable background apps

  Some OS, such as windows are notorious for allowing applications to run in the background, taking valuable resources and energy that could better be used by the games you choose to play. By using your task manager, you can figure out what is running in the background that you are not using and kill it, and this will free valuable resources you need for improved play.  

4) Consider third-party programs

  If you think you’re not up to the task of performing all the above changes, you can invest in third-party game optimization software. The game-boosting programs re an option if you’re scared to tweak the setting manually or the high tip are not working.   Typical game-boosting software tweaks the graphics settings, defrag your system and even overclock your order to improve your gaming performance. The programs provide a one-dial approach to tuning up all your gaming settings automatically.   Even though the programs have the potential to improve your system’s performance by tweaking key settings, the can be risky since changes in the parameters may affect your registry. Speed-up-your-Computer-1024x576 how to improve laptop gaming performance

Links/Sources

 
  • http://h20435.www2.hp.com/t5/The-Next-Bench-Blog/HOW-TO-Improve-laptop-game-performance/ba-p/88482
  • https://www.avg.com/en/signal/9-ways-boost-gaming-rig