Sun GlassFish Enterprise Server v2.1.1 Administration Guide

Using Java Secure Socket Extension (JSSE) Tools

Use keytool to set up and work with JSSE (Java Secure Socket Extension) digital certificates. In the Developer Profile, the Enterprise Server uses the JSSE format on the server side to manage certificates and key stores. In all the profiles, the client side (appclient or stand-alone) uses the JSSE format.

The J2SE SDK ships with keytool, which enables the administrator to administer public/private key pairs and associated certificates. It also enables users to cache the public keys (in the form of certificates) of their communicating peers.

To run keytool, the shell environment must be configured so that the J2SE /bin directory is in the path, or the full path to the tool must be present on the command line. For more information on keytool, see the keytool documentation at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html.

Using the keytool Utility

The following examples demonstrate usage related to certificate handling using JSSE tools:

Generating a Certificate Using the keytool Utility

Use keytool to generate, import, and export certificates. By default, keytool creates a keystore file in the directory where it is run.

  1. Change to the directory where the certificate is to be run.

    Always generate the certificate in the directory containing the keystore and truststore files, by default domain-dir/config. For information on changing the location of these files, see Changing the Location of Certificate Files.

  2. Enter the following keytool command to generate the certificate in the keystore file, keystore.jks:


    keytool -genkey -alias keyAlias-keyalg RSA
     -keypass changeit
     -storepass changeit
    -keystore keystore.jks

    Use any unique name as your keyAlias. If you have changed the keystore or private key password from their default, then substitute the new password for changeit in the above command. The default key password alias is “s1as.”

    A prompt appears that asks for your name, organization, and other information that keytool uses to generate the certificate.

  3. Enter the following keytool command to export the generated certificate to the file server.cer (or client.cer if you prefer):


    keytool -export -alias keyAlias-storepass changeit
     -file server.cer
     -keystore keystore.jks
  4. If a certificate signed by a certificate authority is required, see Signing a Digital Certificate Using the keytool Utility.

  5. To create the truststore file cacerts.jks and add the certificate to the truststore, enter the following keytool command:


    keytool -import -v -trustcacerts
    -alias keyAlias
     -file server.cer
    -keystore cacerts.jks
     -keypass changeit
  6. If you have changed the keystore or private key password from their default, then substitute the new password for changeit in the above command.

    The tool displays information about the certificate and prompts whether you want to trust the certificate.

  7. Type yes, then press Enter.

    Then keytool displays something like this:


    Certificate was added to keystore
    [Saving cacerts.jks]
  8. Restart the Enterprise Server.

Signing a Digital Certificate Using the keytool Utility

After creating a digital certificate, the owner must sign it to prevent forgery. E-commerce sites, or those for which authentication of identity is important can purchase a certificate from a well-known Certificate Authority (CA). If authentication is not a concern, for example if private secure communications is all that is required, save the time and expense involved in obtaining a CA certificate and use a self-signed certificate.

  1. Follow the instructions on the CA's Web site for generating certificate key pairs.

  2. Download the generated certificate key pair.

    Save the certificate in the directory containing the keystore and truststore files, by default domain-dir/config directory. See Changing the Location of Certificate Files.

  3. In your shell, change to the directory containing the certificate.

  4. Use keytool to import the certificate into the local keystore and, if necessary, the local truststore.


    keytool -import -v -trustcacerts
    -alias keyAlias
     -file server.cer
    -keystore cacerts.jks
     -keypass changeit
    -storepass changeit

    If the keystore or private key password is not the default password, then substitute the new password for changeit in the above command.

  5. Restart the Enterprise Server.

Deleting a Certificate Using the keytool Utility

To delete an existing certificate, use the keytool -delete command, for example:

keytool -delete
 -alias keyAlias
 -keystore keystore-name
 -storepass password