Pubcookie's web site is http://www.pubcookie.org/.

Building Pubcookie

Typically seems to be a pain. It required a lot of Makefile hacking. It looks like configure was brain dead, and wasn't able to find /usr/share/apache2/build. Sigh...

Fortunately, I (kbare@CLUB.CC.CMU.EDU) have taken steps to avoid this pain in the future. I built debs that can be used to install Pubcookie in a Debian-friendly way.

Where do things go?

The debs setup configuration/state in the following layout:

• /etc/pubcookie/config
• /etc/pubcookie/login_templates
• /var/lib/pubcookie (directory where pubcookie keys live)

Binaries are:

• /usr/sbin/keyclient
• /usr/sbin/keyserver
• /usr/lib/pubcookie/index.cgi (the login server CGI)

Apache configuration:

• /etc/apache2/mods-available/pubcookie.conf

Settings up a Login Server

First, install the necessary packages.

apt-get install apache2 pubcookie-login-server pubcookie-key-server

Setup the directory the login CGI and images will be served from.

cd /var/www
rsync -e ssh -v -rlt unix:/afs/club/Public/Web/images .
ln -s /usr/share/pubcookie/media/* images
ln -s /usr/lib/pubcookie/login.cgi .
mkdir logout
ln -s ../login.cgi logout

Configure apache. The important things to do are:

• disable the redirect to apache2-default

• Options ExecCGI FollowSymLinks

• AddHandler cgi-script .cgi

• configure SSL

  • add Listen 443 to /etc/apache2/ports.conf

  • add clubca.crt to /usr/share/ca-certificates; run update-ca-certificates

  • add SSLCaCertificatePath /etc/ssl/certs to /etc/apache2/mods-available/ssl.conf

  • add a virtual host using SSL, the same as the existing non-SSL vhost

    • need separate NameVirtualHost *:80 and NameVirtualHost *:443 lines, or else apache gets unhappy

    • SSLEngine on

    • SSLCertificateFile /etc/apache2/webiso.crt

    • SSLCertificateKeyFile /etc/apache2/webiso.key

  • the certificate and key can be copied either from the old machine, or from the club CA directory

• a2enmod ssl

• /etc/init.d/apache2 restart

Configure pubcookie. Fix the the things in /etc/pubcookie/config that are obviously wrong. Add the lines below for Kerberos authentication.

# the credential verifier used by the basic flavor
basic_verifier: kerberos_v5
kerberos5_service_name: login
kerberos5_keytab: /var/lib/pubcookie/login.keytab
append_realm: on
default_realm: CLUB.CC.CMU.EDU

Also, for key server, the following only allows key requests by hosts with a key signed by the club CA.

# keyserver config
keymgt_uri: https://webiso.club.cc.cmu.edu:2222
# keyserver_client_list: webiso.club.cc.cmu.edu
ssl_ca_file: /etc/ssl/certs/clubca.pem

Copy the pubcookie keys from the old login server, into /var/lib/pubcookie.

Extract the login/webiso.club.cc.cmu.edu Kerberos principal into /var/lib/pubcookie/login.keytab.

Fix permissions. For the CGI to read it, /etc/apache2/webiso.key must be owned by root:www-data, with mode 640. All the keys in /var/lib/pubcookie, and the login.keytab should be owned by root:www-data with mode 640.

Test the login server. Hopefully it works... if not, have fun debugging. It will output some information to auth.log.

Copy the club templates into /etc/pubcookie/login_templates.

Setting up an Application Server

New (Debs) Way

apt-get install libapache2-mod-pubcookie pubcookie-key-client

Edit /etc/pubcookie/config. The only things that need to be changed are the ssl_key_file and ssl_cert_file lines. Also make sure the # keyserver config are set correctly. For club use:

keymgt_uri: https://webiso.club.cc.cmu.edu:2222
keyserver_client_list: www.example.com trusted.example.com
ssl_ca_file: /etc/ssl/certs/ca-certificates.crt

The rest are for the login server, which won't run on this machine.

Edit /etc/apache2/mods-available/pubcookie.conf. This will contain the Pubcookie defaults for the webserver. Typically, making it look like one of the apache configuration fragments (pubcookie-club.conf or pubcookie-andrew.conf) will suffice. For club, these are the only lines you'll have to change:

PubcookieSessionKeyFile         /etc/apache2/XXXXX.key
PubcookieSessionCertFile        /etc/apache2/XXXXX.crt

PubcookieLogin                  https://webiso.club.cc.cmu.edu/
PubcookieLoginMethod            POST
PubcookieDomain                 .club.cc.cmu.edu
PubcookieEncryption             AES

These changes may include the need to change pubcookie.conf's PubcookieAuthTypeNames (pubcookie) to match /etc/apache2/httpd.conf's AuthType (WebISO) for the required login url.

Enable the pubcookie module, using a2enmod pubcookie.

See Fetching Keys below.

Old (Collections) Way

Skip this section if you are using debs!

Our current pubcookie build lives in /afs/club/system/dest/@sys/local/pubcookie/003.

Copy it into the stow directory on the host of interest.

One or both of pubcookie-club.conf or pubcookie-andrew.conf (which are apache configuration file fragments) will be needed. If the machine will only authenticate to one of club or andrew, the easiest thing to do is simply copy the appropriate configuration fragment into /etc/apache2/conf.d. Otherwise, copy both into /etc/apache2, and include the appropriate file in each virtual host definition.

mkdir -p /var/pubcookie/keys
chmod 700 /var/pubcookie/keys

Put an appropriate pubcookie configuration in /var/pubcookie/config. There may be the need to change /etc/apache2/mods-available/pubcookie.conf's PubcookieAuthTypeNames (pubcookie) to match /etc/apache2/httpd.conf's AuthType (WebISO) for the required login url.

See Fetching Keys below.

Fetching Keys

Run keyclient to fetch a key from the keyserver.

To fetch an existing key (e.g. if a service is replicated or is being migrated):

keyclient -d

To have the keyserver generate a new key:

• First, on a machine that already has PubCookie configured (and the keyclient binary):

  keyclient -P newhost.club.cc.cmu.edu

• Now that the new machine is permitted to perform key management tasks, you can run keyclient from the new machine to generate a key for it:

  keyclient

You may additionally need to use the -H option, if the virtual host name of the machine is different from its actual host name.

You will also need to fetch the granting certificate.

keyclient -G /var/pubcookie/keys/pubcookie_granting.crt

CategoryServices CategoryClubServices