Using SSL with GlassFish v2
By edort on Nov 30, 2007
Most enterprise applications need to run in a secure environment. Transport Layer Security (TLS)/Secure Sockets Layer (SSL) is a point-to-point secure transport mechanism that can be used for authenticating messages exchanged between a client and a server, and for ensuring message integrity and confidentiality. TLS/SSL (or in this tip, simply "SSL") meets the security requirements of most enterprise application environments, and is widely adopted.
However to participate in SSL-secured message exchanges, the server needs to be enabled as an SSL server. This tip will show you how to enable the GlassFish v2 application server as an SSL server.
In order to follow the steps, you need to understand some basic concepts in SSL such as keys and certificates and understand a concept in GlassFish v2 called profiles.
Keys and Certificates
Two important concepts in SSL are keys and certificates. Keys are used to establish trust and privacy in transactions between the client and the server. SSL uses public key cryptography, which is based on key pairs. Key pairs contain one public key and one private key. If data is encrypted with one key, it can be decrypted only with the other key of the pair.
Certificates are used for authentication. To use SSL, the server must have an associated certificate for each client IP address with which it can connect. The certificate identifies the owner of the server site and provides related information. The certificate is digitally and cryptographically signed by its owner. For sites in which authentication is important, a certificate can be purchased from a well-known trusted certificate authority (CA). However, if authentication is not really a concern, a site can use a self-signed certificate.
GlassFish v2 Profiles
GlassFish v2 supports various usage profiles. Each profile presets configuration parameters for the application server to optimize it for a particular type of use. The three profiles are developer, cluster, and enterprise.
The developer profile optimizes GlassFish v2 for use in a development environment. This means that the configuration parameters support objectives such as fast startup, but don't support things like logging or session replication. The cluster profile sets configuration parameters that enable cluster creation and session replication. A cluster is a group of GlassFish v2 instances that can be managed and monitored as a single logical entity. The enterprise profile optimizes GlassFish v2 for a production environment. It supports things like logging and other security-related features.
Enabling the GlassFish v2 Application Server as an SSL Server
The steps to enable the GlassFish v2 as an SSL server depend on the profile used for the application server. Let's first examine the process if the developer profile is used. Then let's examine the process when the enterprise profile is used.
When the Developer Profile is Used
Recall that a GlassFish v2 profile presets configuration
parameters for a particular type of use. One of those
parameters is Security Store, which identifies how security and
trust-related artifacts such as certificates and keys are
stored. For the developer profile, the Security Store value is
set to JKS. In this case, certificates and keys for the server
are stored in a Java keystore file (
certificates issued by trusted CAs are stored in a certificates
When you install GlassFish v2, it creates a default self-signed certificate as the server certificate. However, if authentication is important in your site, you need to replace the self-signed certificate with a digitally-signed certificate from a CA. This section describes how to replace the self-signed certificate, how to obtain a server certificate from a CA, and how to import the server certificate into the keystore.
The steps described below use
keytool, a key and certificate
Keytool is available in various versions of the
Java Platform, Standard Edition (Java SE) Development Kit (jdk).
However Java SE 6 added some required functions to
instructions below are based on the jdk 6 version of
For detailed information about
keytool, see JDK Tools and
Here are the instructions for enabling GlassFish v2 as an SSL server when the application server is configured with the developer profile.
Delete the default self-signed certificate by issuing the following command (note that the commands in this and subsequent steps are shown on multiple lines for formatting purposes):
keytool -delete -alias s1as -keystore keystore.jks
<store_passwd>is the password for the keystore, for example, "mypass". Note that
s1asis the default alias of the GlassFish v2 keystore.
Generate a new key pair for the application server by issuing the following command:
keytool -genkeypair -keyalg <key_alg>
-keystore keystore.jks -validity <val_days> -alias s1as
<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.
Note that 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.
It's important to ensure that the name of the certificate matches the fully-qualified hostname of your site. If the names don't 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. You should notice that the name of the default self-signed certificate matches the fully-qualified hostname.
Generate a Certificate Signing Request (CSR) by issuing the following command:
keytool -certreq -alias s1as -file <certreq_file>
-keystore keystore.jks -storepass <store_passwd>
<certreq_file>is the file in which the CSR is stored, for example,
<store_passwd>is the password for the keystore, for example, changeit.
Submit the CSR to a CA such as VeriSign. In response, you should receive a signed server certificate. Make sure to import into your browser the CA certificate of the CA 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. Refer to your browser documentation on how to import the CA and intermediate CA certificates into the browser. The CA may provide information on how to import the CA certificates into various browsers such as Mozilla and Internet Explorer.
- Replace the original self-signed certificate with the
certificate you obtained from the CA (stored in a file such
s1as.cert). You can use
keytoolto do this, as follows:
keytool -import -v -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 reply to a CSR.
After running the program, you should see that the certificate
s1asin the GlassFish keystore is no longer the original self-signed certificate, but is now the response certificate from the CA. Here is an example that compares an original
s1ascertificate with a new
s1ascertificate obtained from VeriSign:
Owner: CN=KUMAR, 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
s1as(contains signed cert from CA):
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
After performing these steps, you can restart GlassFish v2 and use the signed server certificate issued by the CA.
When the Cluster Profile is Used
You perform the same steps to enable GlassFish v2 as an SSL server when the application server is configured with the cluster profile as you do for a developer profile. However, in this case you need to ensure that the same server key in replicated in all the application server instances in the cluster.
The Security Store parameter value for the enterprise profile is NSS, which stands for Network Security Services. In an NSS security infrastructure there is no JKS keystore and so there is no default GlassFish keystore.
For the most part, the steps to enable the GlassFish v2
application server as an SSL server are the same when the
enterprise profile is used as when the developer profile is used.
However there are two differences. The first difference pertains
to the first step of the process. Because there is no JKS
keystore, you start the process with an empty keystore
keystore.jks). The second difference pertains to the last step
of the process. Instead of importing the resulting signed
certificate into the JKS keystore, you import it into the NSS
store. In other words, to enable the GlassFish v2 application
server as an SSL server, you perform the same steps as in the
When the Developer Profile is Used section, but you start with
an empty keystore, and you replace step 6 in that section with
the following steps:
Export the private key for the server certificate from the keystore in Privacy Enhanced Mail (PEM) format by issuing the following command:
keyexport.bat -keyfile serverkey.pem
-keystore keystore.jks -storepass changeit -alias s1as
The command invokes the
keyexportutility. You can find the
keyexportpackage, which you can download from the XWSS downloads page in Project Metro
In response you will be prompted for the keystore password. The keystore password is the same as the key password, so you can reply by simply pressing the return key.
This creates a
serverkey.pemfile which contains the server private key under the markers -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY-----.
Append the signed certificate reply from the CA, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- markers, to the
servercert.pemfile. Append the reply just below the END PRIVATE KEY marker.
serverkey.pemfile into a PKCS#12 file (a file with a
.pfxextension). "PKCS" refers to a group of public key cryptography standards devised and published by RSA Security. PKCS#12 defines a file format commonly used to store private keys with accompanying public key certificates, protected with a password-based symmetric key.
There are various tools you can use to convert the
serverkey.pemfile into a PKCS#12 file. One of them is the
openssltool. Here is the command to convert the file using
openssl pkcs12 -export -in serverkey.pem -out s1as.pfx
In response, you will be prompted for the export password. Enter a password such as "changeit" or the GlassFish master password.
s1as.pfxfile will now contain the required signed server certificate and the private key.
Delete the original
s1asself-signed entry, if it exists, by issuing the following command:
certutil -D -n s1as -d $AS_NSS_DB
pk12utilutility to import the new
s1as.pfxfile into the NSS store by issuing the following command:
pk12util -i s1as.pfx -d $AS_NSS_DB
pk12utilis an NSS utility available inside the GlassFish installation template directory for the Enterprise Profile. The utility is used to import or export a PCKS#12 file to and from an NSS store.
In response to the command, you will be prompted for the passwords for the NSS soft token and PKCS#12 file. Supply the appropriate passwords. You should then see the following message indicating that the import was successful:
pk12util: PKCS12 IMPORT SUCCESSFUL
There are two other cases to consider:
The application server profile is the enterprise profile and the server key pair is already in a PKCS#12 file. If there is already an entry in the store with alias
s1as, all you have to do is perform step 4 as described in "When the Enterprise Profile is Used" to delete the original entry:
certutil -D -n s1as -d $AS_NSS_DB
Then perform step 5 to import the new
s1as.pfxfile into the NSS store:
pk12util -i s1as.pfx -d $AS_NSS_DB
If there is no entry in the store with alias
s1as, simply perform step 5.
The application server profile is the developer profile and the server key pair is already in a PKCS#12 file. In this case, all you need to do is perform step 5 as described in When the Enterprise Profile is Used to delete the original
s1asentry. Then use the
pkcs12importutility to import the PCKS#12 file into the GlassFish keystore:
pkcs12import.sh -file s1as.pfx -alias s1as
-keystore keystore.jks -storepass changeit
<exp_password>is the password that was used when the PKCS#12 file was exported, for example, changeit.
You can find the
pkcs12importutility in the
pkcs12importpackage, which you can download from the XWSS downloads page in Project Metro
For More Information
To learn more about SSL with GlassFish see SSL and CRL Checking with GlassFish v2.
Also see the following resources:
- Using JAX-WS-Based Web Services with SSL
- Glassfish with ECC
- Securing Web Applications in Java EE 5
- Configuring Security in GlassFish
- Installing and Configuring SSL Support in the Sun Java System Application Server
- Authentication (Java EE Blueprints)
- Enterprise Java Bean over SSL
- Key Management and PKCS#11 Tokens in Sun Java System Application Server 8.1
- No more 'unable to find valid certification path to requested target'
Kumar Jayanti is a staff engineer at Sun Microsystems and works in the Web Technologies and Standards team. In his current role, Kumar is the lead for the XML and Web Services Security implementation and has also recently taken over responsibility for the GlassFish security module. He has been involved with the web services security effort at Sun since early 2004. Kumar holds an M.Tech degree in Computer Science from IIT Mumbai, India. His areas of interest include distributed computing, CORBA, XML, web services, and security.