As a concrete example, suppose you have decided to set up a Grid where anybody who holds a certificate signed by the UK e-Science Certificate Authority is "trusted". (That is to say: you trust such a person to be who they claim to be. Individual services implemented under OMII_2 may of course be much more selective about who is authorized to do what).
The first thing to note is that any such party will need to obtain at least one e-Science certificate. The e-Science CA issues two kinds of certificates: user certificates and server (or host) certificates. The following instructions on creating a Java keystore apply equally to e-Science server and user certificates.
Assuming you have obtained a certificate that you want to import into either an OMII_2 client-side or an OMII_2 server-side installation, you will first need to create a Java Keystore containing the private and public keys for this certificate. The next subsection provides some general guidelines on how to import your certificate into a Java Keystore. If you already have your keys in a Java Keystore you can skim over this material.
If you generated the keys for your e-Science certificate using a Web browser, you will probably have to go through an intermediate stage of exporting the key to a PKCS12 file. PKCS12 is a standard file format that bundles a certificate with an associated private key. Because it contains a private key, a PKCS12 file (like a Java Keystore) will normally be protected by a password.
These instructions make an assumption that you have a certificate chain with a length of 2. Please refer to What is a keystore? for an explanation of what this means.
Follow the instructions of your CA to obtain a certificate in PKCS12 format. This may involve exporting the user's certificate and private information from the Web browser in which you generated the original key pair. If you export your certificate from a version of the Netscape browser supported by the UK e-Science CA, for example, the default file extension for the PKCS12 file is likely to be .p12. If you use Internet Explorer (IE), it is not recommended that you export the full certificate chain at this stage. The default file extension when using IE will probably be .pfx.
Once you have a PKCS12 file, we suggest you use the Java utility PKCS12Import to convert the PKCS12 to a Java Keystore. PKCS12Import is a simple application that uses Java Security classes from the standard J2SE to do the necessary conversion. It is distributed as part of Jetty but can also be downloaded from the Public Release Download page on the OMII Web site at http://www.omii.ac.uk.
Unzip the file pkcs12import.zip in a suitable working directory, and (in that directory) execute a command like:
java -cp . org.mortbay.util.PKCS12Import my-escience.p12 my-escience.ks
This command takes as input a PKCS12 file called my-escience.p12. It will prompt for the passphrase (password) associated with this file. It will also prompt for the passphrase to be associated with the output keystore. The command creates a Java Keystore called my-escience.ks (assuming a file of this name does not already exist). You should replace the names my-escience.p12 and my-escience.ks with whatever file names are appropriate in your particular case.
The PKCS12Import program sets the certificate password to be the same as the keystore password.
You may find yourself confused by the number of passwords protecting your private keys - you will probably be dealing with up to 3 of them: one for the certificate database in your browser, one for the PKCS12 file, and one for the Java Keystore.
If it runs successfully, the PKCS12Import program will also tell you the alias that should be used to locate the key in the generated store. You need to remember this string! In the case of a UK e-Science server certificate exported from a Netscape browser it is likely to be a string something like:
"<fully-qualified-hostname>'s escience id"
In the case of a certificate exported from Internet Explorer, this alias may be a long (GUID-like), hyphenated string of random-looking digits - for example something like:
If you forget your alias string, you can use the J2SE command keytool to find out what is in the generated keystore, e.g.:
keytool -list -keystore my-escience.ks
At this point the keystore probably only contains a single certificate - your own - and the output of the command above may be something like:
Keystore type: jks
Keystore provider: SUN
Your keystore contains 1 entry
<your alias string>, <date>, keyEntry,
Certificate fingerprint (MD5): <colon-separated string of hex digit pairs>
Experts who are familiar with the JDK keytool may wish to use the keytool - keyclone command to change the alias to a more convenient string.
Before using this keystore with OMII_2 you would normally install the root certificate for your CA as a trusted certificate. This completes the "chain of trust" in your keystore. Download this certificate from your CA, save or export it to (e.g.) a .cer file, then import it into your Java keystore. You may import the file by, for example:
keytool -import -keystore my-escience.ks -file escience-ca.cer
Answer "yes" when asked whether to trust this certificate. (If you wish, you can specify a non-default alias for the CA certificate on the command line, but this is not essential for what follows.)
You should also download the certificate revocation list from your CA, and save it on your target machine for later use. You could save this in a file called escience-crl.pem, for example.
If you wish, you can use the optional -alias flag with the keytool -import option eg.
keytool -import -keystore my-escience.ks -file escience-ca.cer -alias escience-ca
If not specified on the command line, the default value of "mykey" (escience.ca in this case) will be used anyway. The actual value of the alias for the CA certificate is usually unimportant, because this entry just establishes a trust anchor.
Keystores generated as described above can be used in both client and server installations of OMII_2. The following methods may be used to install your externally generated keystore:
Client side: you need to perform a "default install" of the OMII_2 Client, using the automatically generated OMII keystore. You may then subsequently slot in your externally generated non-OMII keystore. At present the client installer does not support the incorporation of non-OMII certificates during OMII_2 Client installation; the OMII is working to rectify this situation.
Server side: though it is possible to install the OMII_2 server and then manually edit files to incorporate a non-OMII keystore, it is preferable to install the non-OMII keystore during the actual OMII_2 server installation.
Changing a Server Certificate: if a certificate expires or has changed for some reason, you will need to perform updates to your OMII_2 server installation.