Administering JSSE Certificates

In the developer profile, the GlassFish Server 3.1 uses the JSSE format on the server side to manage certificates and key stores. In all profiles, the client side (appclient or stand-alone) uses the JSSE format.

The Java SE SDK ships with the keytool utility, which enables you to set up and work with Java Secure Socket Extension (JSSE) digital certificates. You can administer public/private key pairs and associated certificates, and cache the public keys (in the form of certificates) of their communicating peers.

The following topics are addressed here:

To Generate a Certificate by Using keytool
To Sign a Certificate by Using keytool
To Delete a Certificate by Using keytool

To Generate a Certificate by Using `keytool`

By default, the keytool utility creates a keystore file in the directory where the utility is run.

Before You Begin

To run the keytool utility, your shell environment must be configured so that the Java SE /bin directory is in the path, otherwise the full path to the utility must be present on the command line.

Change to the directory that contains the keystore and truststore files.
Always generate the certificate in the directory containing the keystore and truststore files. The default is domain-dir/config.
Generate the certificate in the keystore file, keystore.jks, using the following command format:
```
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 the default (changeit), substitute the new password for changeit. The default key password alias is s1as.
A prompt appears that asks for your name, organization, and other information.
Export the generated certificate to the server.cer file (or client.cer if you prefer), using the following command format:
```
keytool -export -alias keyAlias-storepass changeit
 -file server.cer
 -keystore keystore.jks
```
If a certificate signed by a certificate authority is required, see To Sign a Certificate by Using keytool.
Create the cacerts.jks truststore file and add the certificate to the truststore, using the following command format:
```
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 the default (changeit), substitute the new password.
Information about the certificate is displayed and a prompt appears asking if you want to trust the certificate.
Type yes, then press Enter.
Information similar to the following is displayed:
```
Certificate was added to keystore
[Saving cacerts.jks]
```
To apply your changes, restart GlassFish Server. See To Restart a Domain in Oracle GlassFish Server 3.1 Administration Guide.

Example 1-11 Creating a Self-Signed Certificate in a JKS Keystore by Using an RSA Key Algorithm

RSA is public-key encryption technology developed by RSA Data Security, Inc.

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

Example 1-12 Creating a Self-Signed Certificate in a JKS Keystore by Using a Default Key Algorithm

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

Example 1-13 Displaying Available Certificates From a JKS Keystore

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

Example 1-14 Displaying Certificate information From a JKS Keystore

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

To Sign a Certificate by Using `keytool`

After creating a certificate, the owner must sign the certificate 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).

Note - If authentication is not a concern, for example if private secure communications are all that is required, you can save the time and expense involved in obtaining a CA certificate by using a self-signed certificate.

Delete the default self-signed certificate:
```
keytool -delete -alias s1as -keystore keystore.jks -storepass <store_passwd>
```
where <store_passwd> is the password for the keystore. For example, "mypass". Note that s1as is the default alias of the GlassFish Server keystore.
Generate a new key pair for the application server:
```
keytool -genkeypair -keyalg <key_alg> -keystore keystore.jks 
-validity <val_days> -alias s1as 
```
where <key_alg> is the algorithm to be used for generating the key pair, for example RSA, and <val_days> is the number of days that the certificate should be considered valid. For example, 365.
In addition to generating a key pair, the command wraps the public key into a self-signed certificate and stores the certificate and the private key in a new keystore entry identified by the alias.
For HTTPS hostname verification, it is important to ensure that the name of the certificate (CN) matches the fully-qualified hostname of your site (fully-qualified domain name). If the names do not match, clients connecting to the server will see a security alert stating that the name of the certificate does not match the name of the site.
Generate a Certificate Signing Request (CSR):
```
keytool -certreq -alias s1as -file <certreq_file> -keystore keystore.jks 
-storepass <store_passwd>
```
where <certreq_file> is the file in which the CSR is stored (for example, s1as.csr) and <store_passwd> is the password for the keystore. For example, changeit.
Submit the CSR to a Certificate Authority such as VeriSign http://www.verisign.com/ssl/buy-ssl-certificates/index.html. In response, you should receive a signed server certificate. Make sure to import into your browser the CA certificate of the CA (if not already present) and any intermediate certificates indicated by the CA in the reply.
Store the signed server certificate from the CA, including the markers -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----, into a file such as s1as.cert. Download the CA certificate and any intermediate CA certificates and store them in local files.
Import the CA certificate (if not already present) and any intermediate CA certificates (if not already present) indicated by the CA into the truststore cacerts.jks:
```
keytool -import -v -trustcacerts -alias <CA-Name> -file ca.cert 
 -keystore cacerts.jks -storepass <store_passwd>
```

Replace the original self-signed certificate with the certificate you obtained from the CA, as stored in a file such as s1as.cert:

keytool -import -v -trustcacerts -alias s1as -file s1as.cert
   -keystore keystore.jks -storepass <store_passwd>

When you import the certificate using the same original alias s1as, keytool treats it as a command to replace the original certificate with the certificate obtained as a reply to a CSR.

After running the command, you should see that the certificate s1as in the keystore is no longer the original self-signed certificate, but is now the response certificate from the CA.

Consider the following example that compares an original s1as certificate with a new s1as certificate obtained from VeriSign:

Original s1as (self-signed):

Owner: CN=FQDN, OU=Sun Java System Application Server, O=Sun
Microsystems, L=Santa Clara, ST=California, C=US
Issuer: CN=KUMAR, OU=Sun Java System Application Server, O=Su
n Microsystems, L=Santa Clara, ST=California, C=US
Serial number: 472acd34
Valid from: Fri Nov 02 12:39:40 GMT+05:30 2007 until: Mon Oct
30 12:39:40 GMT+05:30 2017

New s1as (contains signed cert from CA):

Owner: CN=FQDN, OU=Terms of use at www.verisign.com/cps/test
ca (c)05, OU=Sun Java System Application Server, O=Sun Micros
ystems, L=Santa Clara, ST=California, C=US
Issuer: CN=VeriSign Trial Secure Server Test CA, OU=Terms of
use at https://www.verisign.com/cps/testca (c)05, OU="For Test
Purposes Only. No assurances.", O="VeriSign, Inc.", C=US
Serial number: 1375de18b223508c2cb0123059d5c440
Valid from: Sun Nov 11 05:30:00 GMT+05:30 2007 until: Mon Nov
26 05:29:59 GMT+05:30 2007

To apply your changes, restart GlassFish Server.
See To Restart a Domain in Oracle GlassFish Server 3.1 Administration Guide.

Example 1-15 Importing an RFC/Text-Formatted Certificate Into a JKS Keystore

Certificates are often stored using the printable encoding format defined by the Internet Request for Comments (RFC) 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}

Example 1-16 Exporting a Certificate From a JKS Keystore 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}

Example 1-17 Exporting a Certificate From a JKS Keystore in RFC/Text Format

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

To Delete a Certificate by Using `keytool`

Use the keytool -delete command to delete an existing certificate.

Delete a certificate using the following command format:

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

Example 1-18 Deleting a Certificate From a JKS Keystore

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

Skip Navigation Links
Exit Print View
	Oracle GlassFish Server 3.1 Security Guide