Client Certificates

Richard Jones
September 1, 2003
updated April 5, 2006

The OpenShop framework uses client certificates the authenticate users. A client certificate is issued on the behalf of a user by a Certificate Authority who can vouch for the reliability of the user's identity. Currently the framework recognizes certificates signed either globally by the DOE Science Grid authority or locally by the OpenShop Framework authority. Client certificates are transported and stored in files encrypted according to the PKCS12 standard, and normally have extension .pfx (IE convention) or .p12 (Mozilla convention). PKCS12 files are protected by a single password, which is supposed to protect the certificate and the public/private key pair inside from being stolen. The mere possession of a certificate is not enough to grant a user access; the certificate must be registered in the browser and/or plugin being used to communicate with the OpenShop web services.

Who are the recognized certificate authorities?

Any client certificate signed by one of the recognized CA's listed below are granted member access to the OpenShop web services. Clicking on one of the listed links will take you to a web site from where you can access and download the CA root certificate.

OpenShop Certificate Authority
To download the CA certificate into your browser for future use, you can select your browser type using the buttons near the top of the page and press the "Load CA Certificate" button. This needs to be done only once on any given installation.
U.S. Department of Energy Grid Certificates Authority
To download the CA certificate into your browser for future use, select the "Retrieval" tab and then click on "Import CA certificate chain" in the list in the left-hand column. This takes you to a page which gives you a number of options for examining and downloading the CA certificate. This needs to be done only once on any given installation.

How do I obtain a personal certificate from one of these CA's?

If you are a researcher with long-term interest in grid-enabled scientific applications then you should apply to the US Department of Energy Grid Certificates authority. If you would just like a temporary certificate that would allow you to work on one of the projects on this web site then send me an email summarizing your needs.

How do I get the browser to recognize my personal certificate?

Netscape/Mozilla and IE both use a similar interface to user certificates. Let us assume that you have a personal certificate in a .pfx file sitting in your home directory (linux) or on the desktop (windows/Mac). To import the certificate into the IE browser, start IE and go to Tools->Internet Options, select the Content tab and click the button labeled Certificates. Press the Import button and follow the instructions of the wizard. You will be instructed at one point to enter the password of the .pfx file. If the import is successful, the new certificate should appear in the list under the Personal tab, Certificates.

For Netscape/Mozilla, go to Edit->Preferences and find the Certificates pane under Privacy & Security. From there press the button Manage Certificates, then Import and follow the wizard. As for IE, you must enter the password for the pkcs12 file for the import to succeed. If the import worked then the certificate should be listed in the frame above the Import button.

How do I get the browser to pass my personal certificate to the server?

When you issue a request for a web page over SSL (address starting with https) it is the server that controls the handshake procedure that sets up the encrypted channel. If the server has been set up to expect client certificates then it will issue a request to the browser for a user certificate signed by one of the signing authorities that are recognized by the server. Only client certificates that would be recognized by the server are allowed to be returned by the browser, which means that sometimes the it sends back nothing in response to a server's request for a client certificate, even if a number of certificates have been registered in the browser which are signed by various other certificate authorities. If more than one of the certificates in the browser bank would be recognized by the server, the user is prompted for which one represents the identity that he would like to present to the server.

How do I get the GUI applet to pass my personal certificate to the server?

As of version 1.4, the java browser plugin for Netscape/Mozilla and IE keeps a completely separate table of client and server certificates from that maintained by the browser itself. This sounds like madness, but the developers claim that it makes perfect sense. So in order to authenticate yourself from within the GUI applet, you need first to load your personal certificate into the java plugin. This is done using the java plugin Control Panel. From within Windows and Mac, it is found in the ordinary control panels. To start the plugin control panel from linux, look in your jdk installation for the executable jre/bin/ControlPanel.

For jre v1.4.x (deprecated):
Once you have the plugin control panel open, go to the Advanced tab. At the bottom of the pane is a window for entering run-time parameters for the plugin. Enter the following text into the run-time parameters window.
-Djavax.net.ssl.keyStore=path to your .pfx file -Djavax.net.ssl.keyStorePassword=password to your .pfx file -Djavax.net.ssl.keyStoreType=PKCS12
Apply the changes, close the control panel, and restart the browser so as to reload the plugin. Note that the above operations apply both to IE and to Netscape/Mozilla because the same plugin runs in both browsers. It is unfortunate that the pkcs12 certificate password must be saved in plain text in the control panel like this. Perhaps this will be remedied in the next release of the plugin. To offset the risk, make sure that the .pfx file is saved with no group or world read permission.
For jre v1.5.x and later:
The certificate registry for the java vm is now managed in much the same way as the browsers do it. Once you have the plugin control panel open, go to the Security tab and select the button labeled Certificates. At the top of the Certificates page there is a pull-down menu where you can select the different certificate lists for the java vm, including such things as trusted web sites, trusted CA signers, and client certificates. Under each of these headings the user can import new certificates to be appended to the existing list, delete existing certificates from the list, or display the data from the database. Here you should import your client certificate for the openShop framework, supplying a password by which the certificate is encrypted into the java vm keystore. It is a good idea to keep the passwords the same between the browser software security device and the java vm keystores, as they tend the same information.

I did all of that, but still the server does not see my personal info!

One helpful tool for finding out what is going wrong with client authentication is the java console. It is found under Tools->Web Development with Netscape/Mozilla and under Tools->Sun Java Console with IE. To save time, cut any applet startup error messages out of the java console window and paste it into an email to me at the address below.

This page created and maintained by Richard T. Jones.