Configuring Transport Layer Security (TLS)

As described in Certificates and SSL in Oracle GlassFish Server 3.1 Security Guide, Secure Sockets Layer (SSL) is the most popular standard for securing Internet communications and transactions. Secure web applications use HTTPS (HTTP over SSL). The HTTPS protocol uses certificates to ensure confidential and secure communications between server and clients. The newest version of the SSL standard is called Transport Layer Security (TLS). GlassFish Server supports the SSL 3.0 and the TLS 1.0 encryption protocols.

The following procedure lists the major tasks for configuring GlassFish Server for TLS/SSL. The procedure also provides cross-references to detailed instructions for performing each task.

To Configure GlassFish Server for TLS/SSL

Set up the keystore and truststore for a domain.
By default, the keystore (keystore.jks) and truststore (cacerts.jks) for a domain are created in the domain-dir/config directory when you create the domain. The domain creation process creates a primary (private) key and a self-signed certificate for the DAS, and a separate private key and self-signed certificate for remote instances.
When you create a domain you can use the create-domain(1) subcommand --keytooloptions to specify the common name (CN) of the host that is to be used for the self-signed certificate. By default, the name is the fully-qualified name of the host where you run the create-domain subcommand.
GlassFish Server generates self-signed certificates suitable for internal testing. The self-signed certificates that GlassFish Server generates are typically not trusted by clients by default because a certificate authority does not vouch for the authenticity of the certificate. For example, browsers will warn you, let you view the certificate, and ask you to reject the certificate, accept it once, or accept it indefinitely.
You can use your tool of choice, such as keytool, to list the default self-signed certificates in the keystore, similar to the following:

Note - You can list some limited contents of the keystore without supplying a password. However, for a request that affects the private key, such as the keytool.exe --certreq option, the keystore password is required.

keytool.exe -list -v -keystore keystore.jks
```
Enter keystore password:

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 2 entries

Alias name: glassfish-instance
Creation date: Apr 14, 2011
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=system01.somedomain-instance, OU=GlassFish, O=Oracle Corporation,
L=Santa Clara, ST=California, C=US
Issuer: CN=system01.somedomain-instance, OU=GlassFish, O=Oracle Corporation,
 L=Santa Clara, ST=California, C=US
Serial number: 4da74a98
Valid from: Thu Apr 14 15:27:20 EDT 2011 until: Sun Apr 11 15:27:20 EDT 2021
Certificate fingerprints:
         MD5:  00:FA:CF:65:19:7B:B2:02:62:66:DE:68:7B:BA:AE:93
         SHA1: 11:E2:06:54:84:B3:67:8C:2E:AD:B6:4C:E9:E1:B9:A0:07:A7:CE:B9
         Signature algorithm name: SHA1withRSA
         Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 5D 37 CB 75 70 B8 52 4B   91 C6 A7 D3 FB BF 22 3F  ]7.up.RK......"?
0010: 5D AE D7 74                                        ]..t
]
]



*******************************************
*******************************************


Alias name: s1as
Creation date: Apr 14, 2011
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=system01.somedomain, OU=GlassFish, O=Oracle Corporation, L=Santa C
lara, ST=California, C=US
Issuer: CN=system01.somedomain, OU=GlassFish, O=Oracle Corporation, L=Santa
Clara, ST=California, C=US
Serial number: 4da74a94
Valid from: Thu Apr 14 15:27:16 EDT 2011 until: Sun Apr 11 15:27:16 EDT 2021
Certificate fingerprints:
         MD5:  23:EA:3F:89:E6:34:31:21:C8:D6:47:88:30:05:3B:50
         SHA1: 8B:9E:86:AE:E4:71:C4:8E:70:99:DB:3E:93:6C:BC:E3:DB:15:D1:B6
         Signature algorithm name: SHA1withRSA
         Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 87 BB 44 61 54 3C 09 15   8C 4F 1E 13 8B 37 46 AB  ..DaT<...O...7F.
0010: 66 27 F9 A2                                        f'..
]
]
```
You can instead have GlassFish Server use trusted certificates for this purpose by adding one or more valid certificates and CA root in the keystore and truststore, respectively. Oracle strongly recommends that you use certificates signed by an accepted CA in a production environment.
Keep the following points in mind:
- If GlassFish Server uses self-signed certificates, you need to include them directly in the client-side truststore.
- If GlassFish Server uses certificates that are signed using a CA, import the CA root certificate into the client's truststore.
- If you use certificates other than the GlassFish Server defaults, take note of the alias names you use. You will need the alias names later in this procedure when you configure the HTTP Listener for SSL.
For more information on using your own certificates, see the following documentation:
- To Generate a Certificate by Using keytool in Oracle GlassFish Server 3.1 Security Guide
- To Sign a Certificate by Using keytool in Oracle GlassFish Server 3.1 Security Guide
Optionally, configure the client for two-way SSL.
With two-way SSL (SSL with client authentication), GlassFish Server presents a certificate to the client and the client presents a certificate to GlassFish Server.
In this case, you must ensure that GlassFish Server is able to validate the certificate that the client uses to digitally sign its request, and that GlassFish Server in turn uses to encrypt its responses to the client. Do one of the following:
- Make sure the client uses a digital certificate that GlassFish Server automatically trusts because it has been issued by a trusted certificate authority.
- Make sure the client uses an individual certificate that is already in the GlassFish Server keystore and therefore already trusted.
Create a Listener Port
See To Create an Internet Connection in Oracle GlassFish Server 3.1 Administration Guide.

Note - An HTTP listener, also known as a network listener, is a listen socket that has an Internet Protocol (IP) address, a port number, a server name, and a default virtual server. Each virtual server provides connections between the server and clients through one or more listeners.
Each HTTP listener has an associated HTTP protocol.
1. Ensure that the server is running.
  Remote subcommands require a running server.
2. Create an HTTPS protocol by using the create-protocol(1) subcommand with the --securityenabled option.
  (The listener named http-listener-2 has security (SSL) enabled by default. To use this built-in http-listener-2 HTTPS protocol, skip this step.)
  See To Create a Protocol in Oracle GlassFish Server 3.1 Administration Guide.
3. Create an HTTP configuration for this protocol by using the create-http(1) subcommand.
  (If you used the built-in http-listener-2 HTTPS protocol, skip this step.)
  See To Create an HTTP Configuration in Oracle GlassFish Server 3.1 Administration Guide.
4. Optionally, create a transport by using the create-transport(1) subcommand.
  To use the built-in tcp transport, skip this step. You generally do not need another transport in addition to the default tcp transport.
  See To Create a Transport in Oracle GlassFish Server 3.1 Administration Guide.
5. Optionally, create a thread pool by using the create-threadpool(1) subcommand.
  To avoid using a thread pool, or to use the built-in http-thread-pool thread pool, skip this step.
  For additional thread pool information, see Chapter 5, Administering Thread Pools, in Oracle GlassFish Server 3.1 Administration Guide.
6. Create an HTTP listener by using the create-network-listener(1) subcommand.
  Specify the previously chosen protocol, and optionally a transport and thread pool.
```
asadmin> create-network-listener --listenerport 7272 
protocol http-listener-2 --enabled=true sampleListener
Command create-network-listener executed successfully.
```
  For more information, see To Create an HTTP Network Listener in Oracle GlassFish Server 3.1 Administration Guide.
7. Configure the HTTP Listener for SSL
  The create-ssl(1) subcommand creates and configures the SSL element in the selected HTTP listener, IIOP listener, or IIOP service to enable secure communication on that listener/service.
  You use the create-ssl subcommand to specify SSL2, SSL3, TLS, to set cipher suites, to enable two-way (client-auth) SSL, and so forth. By default, SSL3 and TLS are enabled and all cipher suites are enabled.
  If you enabled two-way SSL for the client, you must also enable it for GlassFish Server by setting the -clientauthenabled option.
  You must specify the alias (--certname) of the certificate in this subcommand.
  For example, this example enables the HTTP listener named sampleListener for SSL with client authentication enabled. The alias name s1as identifies the default GlassFish Server certificate.
```
asadmin> create-ssl --type http-listener 
--certname s1as --clientauthenabled sampleListener
Command create-ssl executed successfully.
```
To activate your changes, restart GlassFish Server.

Shortcut for Configuring GlassFish Server for TLS/SSL

You can use the create-http-listener(1) subcommand to create a network listener configured for SSL that uses the HTTPS protocol without having to first create a protocol, transport, or HTTP con figuration. This subcommand is a convenient shortcut, but it gives access to only a limited number of options.

Shortcut: To Configure GlassFish Server for TLS/SSL

Set up the keystore and truststore for a domain.
Optionally, configure the client for two-way SSL.
Create an HTTP Network Listener with the create-http-listener subcommand
1. Ensure that the server is running.
  Remote subcommands require a running server.
2. Run create-http-listener with the --securityenabled option.
  If the --securityenabled options is set to true, the HTTP listener runs SSL. The security setting globally enables or disables SSL by making certificates available to the server instance. The default value is false.
  For example:
```
asadmin> create-http-listener --listeneraddress 0.0.0.0
--listenerport 443 --securityenabled=true --enabled=true 
--default-virtual-server server sampleListener
Command create-http-listener executed successfully.
```
  You cannot use the create-http-listener subcommand to specify SSL2, SSL3, TLS, to set cipher suites, or to enable client authentication. Instead, when you set --securityenabled to true, both SSL3 are TLS are enabled, all cipher suites are chosen, and client authentication is not enabled. With the exception of the client authentication case, these defaults should be acceptable in most cases.
  To change the defaults, you need to explicitly set these elements. For example:
```
asadmin> get configs.config.server-config.network-con fig.protocols.protocol.sampleListener.ssl.client-auth-enabled
configs.config.server-config.network-config.protocols.protocol.sampleListener.ss
l.client-auth-enabled=false
Command get executed successfully.

asadmin> set configs.config.server-config.network-con fig.protocols.protocol.sampleListener.ssl.client-auth-enabled=true
configs.config.server-config.network-config.protocols.protocol.sampleListener.ss
l.client-auth-enabled=true
Command set executed successfully.
```
For more information, see To Create an HTTP Network Listener in Oracle GlassFish Server 3.1 Administration Guide.
To activate your changes, restart GlassFish Server.

Skip Navigation Links
Exit Print View
	Oracle GlassFish Server 3.1 Quick Start Guide