Chapter 12 Managing Keys and Certificates

Using Netscape to manage certificates on the client

PKCS #11 is an RSA standard that specifies an API called Cryptoki, which performs cryptographic functions, such as key-pair and certificate management.

Netscape 4.0x supplies a PKCS #11 module that allows you to manage the client-side certificates. Sybase also provides a PKCS #11 module that allows you to manage your certificates. Sybase recommends that you install the Sybase PKCS #11 module into Netscape, which provides immediate access to the EAServer sample server certificates.

Installing Sybase PKCS #11 into Netscape 4.0x

Start Netscape 4.0x, then:

Select Communicator | Security Info from the window. Or, you can click the Security icon (the padlock) in the tool bar.
Click on Cryptographic Modules.
Click Add. You see a new dialog, Create a New Security Module.
For Security Module Name, enter "Sybase PKCS".
For Security Module File, type the full path to your libjsybcki file, then click OK. For example, on NT, enter:

i:\Program Files\Sybase\Jaguar CTS\dll\libjsybcki.dll

On UNIX, enter:

/work/JagPKS/lib/libjsybcki_r.so
You should see a prompt asking for a Sybase password or PIN. Enter "sybase". If you do not see this prompt, verify the path to the DLL/shared object.
After entering the password, you see Sybase PKCS listed as a security module. Click on the Sybase PKCS module, then select View/Edit. A new window, the Edit Security Module window, displays. This window contains controls for the Sybase PKCS module.
Click "More Info" in the new window, and verify that the state is "Ready" in the Token/Slot Information window. Click OK to close the Token/Slot Information window.
You can change the Sybase PKCS module password by clicking Change Password in the Edit Security Module window. Click OK to close this window.

When both EAServer and Netscape run on the same machine, they share Sybase PKCS #11 database files. If you change the PIN, you must use the new PIN when you log in to either EAServer or Netscape. Sybase suggests that you change your PIN through Security Manager, which automatically propagates the PIN changes to the security profiles. If you change the PIN through Netscape, you must also change the PIN in all of the security profiles; otherwise EAServer secure listeners using those security profiles may not start the next time you restart the server. See "Changing the user PIN" for information about changing the PIN in Security Manager.

If you modify the PIN through Security Manager, you need to restart Netscape for the changes to take effect. If you modify the PIN through Netscape, while the server is running, shut down and restart the server. Supply the new PIN to connect to Security Manager.

Obtaining a key pair and certificate

Sybase PKCS #11 includes two sample server certificates. You can use these certificates when communicating with EAServer from your browser. You can also request new certificates from your CA or certificate server and install them in your browser.

In general, the steps involved in obtaining a certificate from a CA are:

Initiate a certificate request operation by connecting to a Web server hosting the public-key infrastructure (PKI) administration HTML pages for the CA/PKI.
On the PKI administration Web page, complete the identity information form required by the CA.
Netscape generates a key pair, and stores the private key in the PKCS #11 module. The public key is digitally signed and forwarded to the CA.

You must be logged in to the PKCS #11 module to store or access the private key.
The CA approves the request, generates the certificate, and makes the certificate downloadable by way of a URL.
The CA notifies you of certificate approval and URL location through
e-mail.
Open the URL to get the certificate. You must log in to the PKCS #11 module using the previously established PIN. The browser automatically installs the certificate, locates the previously stored matching private key using the key ID, and sets the user-specified label.

SSL certificate information in servlets

This section describes how to include the client's certificate information into Java servlets that are hosted by EAServer.

If you are using JDK 1.2, you can obtain SSL certificate information about the client as follows:

java.security.cert.X509Certificate peerX509;
ServletRequest request;

peerX509 = (java.security.cert.X509Certificate)
       request.getAttribute
       ("javax.servlet.request.X509Certificate");

Where request is the ServletRequest parameter passed in the doXXX() method.See section 5.7 of the Java Servlet Specification version 2.2 for more information.

If you are not using JDK 1.2, you can obtain SSL certificate information about the client as follows:

import CtsSecurity.*;

CtsSecurity.X509Certificate peerX509;

peerX509 = (CtsSecurity.X509Certificate)request.getAttribute( "com.sybase.jaguar.servlet.request.X509Certificate");

Methods in CtsSecurity.X509Certificate and java.security.cert.X509Certificate are very similar. java.security.cert.X509Certificate documentation is available as part of the JDK documentation. CtsSecurity.X509Certificate documentation is available in the EAServer repository documentation.