Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide

- Previous: Admin Console Tasks for Connector Connection Pools
- Next: Further Information

# Working with Certificates and SSL

- About Certificate Files

- To change the location of certificate files

- Using Java Secure Socket Extension (JSSE) Tools

## About Certificate Files

Installation of the Application Server generates a digital certificate in JSSE (Java Secure Socket Extension) format suitable for internal testing. By default, the Application Server stores its certificate information in two files in the domain-dir`/config` directory:

- Keystore file, `keystore.jks`, contains the Application Server’s certificate, including its private key. The keystore file is protected with a password, initially `changeit`. Change the password using `keytool`. For more information about `keytool`, read Using the keytool Utility.

  Each keystore entry has a unique alias. After installation, the Application Server keystore has a single entry with alias `s1as`.

- Truststore file, `cacerts.jks`, contains the Application Server’s trusted certificates, including public keys for other entities. For a trusted certificate, the server has confirmed that the public key in the certificate belongs to the certificate’s owner. Trusted certificates generally include those of certification authorities (CAs).

  In the Platform Edition, on the server side, the Application Server uses the JSSE format, which uses `keytool` to manage certificates and key stores. In the Enterprise Edition, on the server side, the Application Server uses NSS, which uses `certutil` to manage the NSS database which stores private keys and certificates. In both editions, the client side (appclient or stand-alone), uses the JSSE format.

  By default, the Application Server is configured with a keystore and truststore that will work with the example applications and for development purposes. For production purposes, you may wish to change the certificate alias, add other certificates to the truststore, or change the name and/or location of the keystore and truststore files.

See also:

- To change the location of certificate files

### To change the location of certificate files

The keystore and truststore files provided for development are stored in the domain-dir`/config` directory.

1. In the Admin Console tree, select the Application Server node.

2. Select JVM Settings.

3. Click the JVM Options tab.

4. On the JVM Options page, add or modify the following values in the Value field to reflect the new location of the certificate files:

       -Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/path/ks-name
       -Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/path/ts-name

   where ks-name is the keystore file name and ts-name is the trust store file name.

5. Click Save.

6. Restart the Application Server if Restart Required displays in the console.

##### See Also

- About Certificate Files

- Using Java Secure Socket Extension (JSSE) Tools

## Using Java Secure Socket Extension (JSSE) Tools

Use `keytool` to set up and work with JSSE (Java Secure Socket Extension) digital certificates. In the Platform Edition, the Application Server uses the JSSE format on the server side to manage certificates and key stores. In both the Platform Edition and Enterprise Edition, 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:

- Create a self-signed certificate in a keystore of type JKS using an RSA key algorithm. RSA is public-key encryption technology developed by RSA Data Security, Inc. The acronym stands for Rivest, Shamir, and Adelman, the inventors of the technology.

      keytool  -genkey -noprompt -trustcacerts -keyalg RSA -alias ${cert.alias}
      -dname  ${dn.name} -keypass ${key.pass} -keystore ${keystore.file}
      -storepass ${keystore.pass}

  Another example of creating a certificate is shown in To generate a certificate using the `keytool` utility.

- Create a self-signed certificate in a keystore of type JKS using the default key algorithm.

      keytool -genkey -noprompt -trustcacerts -alias ${cert.alias} -dname
      ${dn.name} -keypass ${key.pass} -keystore ${keystore.file} -storepass
      ${keystore.pass}

  An example of signing a certificate is shown in To sign a digital certificate using the `keytool` utility

- Display available certificates from a keystore of type JKS.

      keytool -list -v  -keystore ${keystore.file} -storepass ${keystore.pass}

- Display certificate information from a keystore of type JKS.

      keytool  -list -v  -alias ${cert.alias} -keystore ${keystore.file}
      -storepass ${keystore.pass}

- Import an RFC/text-formatted certificate into a JKS store. Certificates are often stored using the printable encoding format defined by the Internet RFC (Request for Comments) 1421 standard instead of their binary encoding. This certificate format, also known as Base 64 encoding, facilitates exporting certificates to other applications by email or through some other mechanism.

      keytool -import -noprompt -trustcacerts -alias ${cert.alias} -file
      ${cert.file} -keystore ${keystore.file} -storepass ${keystore.pass}

- Export a certificate from a keystore of type JKS in PKCS7 format. The reply format defined by the Public Key Cryptography Standards #7, Cryptographic Message Syntax Standard, includes the supporting certificate chain in addition to the issued certificate.

      keytool  -export -noprompt  -alias ${cert.alias} -file ${cert.file}
      -keystore ${keystore.file} -storepass ${keystore.pass}

- Export a certificate from a keystore of type JKS in RFC/text format.

      keytool  -export -noprompt -rfc  -alias ${cert.alias} -file
      ${cert.file} -keystore ${keystore.file} -storepass ${keystore.pass}

- Delete a certificate from a keystore of type JKS.

      keytool  -delete -noprompt -alias ${cert.alias}  -keystore ${keystore.file}
      -storepass ${keystore.pass}

  Another example of deleting a certificate from a keystore is shown in Deleting a Certificate Using the `keytool` Utility

See also:

- To generate a certificate using the `keytool` utility

- To sign a digital certificate using the `keytool` utility

- Deleting a Certificate Using the `keytool` Utility

### To generate 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 To change 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.

   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 To sign 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

   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.

6. Type `yes`, then press Enter.

   Then `keytool` displays something like this:

       Certificate was added to keystore
       [Saving cacerts.jks]

7. Restart the Application Server.

##### See Also

- To change the location of certificate files

- Using the keytool Utility

- To sign a digital certificate using the `keytool` utility

- Deleting a Certificate Using the `keytool` Utility

### To sign 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 To change 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 Application Server.

##### See Also

- About Certificate Files

- To change the location of certificate files

- Using the keytool Utility

- To generate a certificate using the `keytool` utility

- Deleting a Certificate Using the `keytool` Utility

### 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

For a complete list of possible options for the `-delete` command, refer to the `keytool` documentation at `http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html`.

See Also:

- About Certificate Files

- To change the location of certificate files

- Using Java Secure Socket Extension (JSSE) Tools

- Using the keytool Utility

- To generate a certificate using the `keytool` utility

- To sign a digital certificate using the `keytool` utility

- Previous: Admin Console Tasks for Connector Connection Pools
- Next: Further Information

- © 2010, Oracle Corporation and/or its affiliates