|Skip Navigation Links|
|Exit Print View|
|Oracle GlassFish Server Message Queue 4.5 Administration Guide|
This section explains how to set up a connection service based on the Secure Socket Layer (SSL) standard, which enables delivery of encrypted messages over the connection. Message Queue supports the following SSL-based connection services:
The ssladmin service creates a secure, encrypted connection between the Message Queue Command utility (imqcmd) and a broker, using the TCP/IP transport protocol. Encrypted connections are not supported for the Administration Console (imqadmin).
A JMX connector that supports secure, encrypted communication between a JMX client and a broker's MBean server using the RMI transport protocol over TCP.
The remainder of this section describes how to set up secure connections over TCP/IP, using the ssljms, ssladmin, and cluster connection services. For information on setting up secure connections over HTTP with the httpsjms service, see Appendix C, HTTP/HTTPS Support.
To use an SSL-based connection service over TCP/IP, you generate a public/private key pair using the Key Tool utility (imqkeytool). This utility embeds the public key in a self-signed certificate that is passed to any client requesting a connection to the broker, and the client uses the certificate to set up an encrypted connection. This section describes how to set up an SSL-based service using such self-signed certificates.
For a stronger level of authentication, you can use signed certificates verified by a certification authority. The use of signed certificates involves some additional steps beyond those needed for self-signed certificates: you must first perform the procedures described in this section and then perform the additional steps in Using Signed Certificates.
Message Queue's support for SSL with self-signed certificates is oriented toward securing on-the-wire data, on the assumption that the client is communicating with a known and trusted server. Configuring SSL with self-signed certificates requires configuration on both the broker and client:
The following sequence of procedures are needed to set up an SSL-based connection service for using self-signed certificates:
Note - Starting with release 4.0, the default value for the client connection factory property imqSSLIsHostTrusted is false. If your application depends on the prior default value of true, you need to reconfigure and to set the property explicitly to true. In particular, old or new clients using self-signed certificates should set this property to true; for example:java -DimqConnectionType=TLS -DimqSSLIsHostTrusted=true MyApp
The administration tool imqcmd is also affected by this change. In addition to using the –secure option to specify that it uses a SSL-based admin connection service, the imqSSLIsHostTrusted should be set to true when connecting to a broker configured with a self-signed certificate. You can do this as follows:imqcmd list svc -secure -DimqSSLIsHostTrusted=true
Alternatively, you can import the broker's self-signed certificate into the client runtime trust store. Use the procedure in To Install a Signed Certificate.
Generate a self-signed certificate.
Enable the desired SSL-based connection services in the broker. These can include the ssljms, ssladmin, or cluster connection services.
Start the broker.
Run the Key Tool utility (imqkeytool) to generate a self-signed certificate for the broker. (On Solaris and Linux operating systems, you may need to run the utility as the root user in order to have permission to create the keystore file.) The same certificate can be used for all SSL-based connection services (ssljms, ssladmin, cluster connection services, and the ssljmxrmi connector).
The Key Tool utility prompts you for a key store password:
The Keystore utility prompts you for identifying information from which to construct an X.500 distinguished name. The following table shows the prompts and the values to be provided for each. Values are case-insensitive and can include spaces.
The Key Tool utility displays the information you entered for confirmation. For example,
Is CN=mqserver.sun.com, OU=purchasing, ON=Acme Widgets, Inc., L=San Francisco, ST=California, C=US correct?
The utility asks for a password to lock the key pair (key password).
This will set the same password for both the key password and the keystore password.
Caution - Be sure to remember the password you specify. You must provide this password when you start the broker, to allow the broker to open the keystore file. You can store the keystore password in a password file (see Password Files).
The Key Tool utility generates a self-signed certificate and places it in Message Queue’s keystore file. The keystore file is located in IMQ_HOME/etc by default.
The following are the configurable properties for the Message Queue keystore for SSL-based connection services:
In some circumstances, you may need to regenerate a key pair in order to solve certain problems: for example, if you forget the key store password or if the SSL-based service fails to initialize when you start a broker and you get the exception:java.security.UnrecoverableKeyException: Cannot recover key
(This exception may result if you provided a key password different from the keystore password when you generated the self-signed certificate.)
The file is located in IMQ_HOME/etc by default.
The command will generate a new key pair, as described above.
By default, the property includes the jms and admin connection services. Add the SSL-based service or services you wish to activate (ssljms, ssladmin, or both):imq.service.activelist=jms,admin,ssljms,ssladmin
Note - When you start a broker or client with SSL, you may notice a sharp increase in CPU usage for a few seconds. This is because the JSSE (Java Secure Socket Extension) method java.security.SecureRandom, which Message Queue uses to generate random numbers, takes a significant amount of time to create the initial random number seed. Once the seed is created, the CPU usage level will drop to normal.
Put the keystore password in a password file, as described in Password Files and set the imq.passfile.enabled property to true. You can now do one of the following:
imqbrokerd -passfile /passfileDirectory/passfileName
You are prompted for the keystore passwrd.
The procedure for configuring a client to use an SSL-based connection service differs depending on whether it is an application client (using the ssljms connection service) or a Message Queue administrative client such as imqcmd (using the ssladmin connection service.)
For application clients, you must make sure the client has the following .jar files specified in its CLASSPATH variable:
Once the CLASSPATH files are properly specified, one way to start the client and connect to the broker’s ssljms connection service is by entering a command like the following:java -DimqConnectionType=TLS clientAppName
This tells the connection to use an SSL-based connection service.
For administrative clients, you can establish a secure connection by including the -secure option when you invoke the imqcmd command: for example,imqcmd list svc -b hostName:portNumber -u userName -secure
where userName is a valid ADMIN entry in the Message Queue user repository. The command will prompt you for the password.
Listing the connection services is a way to verify that the ssladmin service is running and that you can successfully make a secure administrative connection, as shown in Example 9-6.
Example 9-6 Connection Services Listing
Signed certificates provide a stronger level of server authentication than self-signed certificates. You can implement signed certificates only between a client and broker, and currently not between multiple brokers in a cluster. This requires the following extra procedures in addition to the ones described in Using Self-Signed Certificates. Using signed certificates requires configuration on both the broker and client:
The following procedures explain how to obtain and install a signed certificate.
Information about the keytool command can be found at
Here is an example:keytool -certreq -keyalg RSA -alias imq -file certreq.csr -keystore /etc/imq/keystore -storepass myStorePassword
This generates a CSR encapsulating the certificate in the specified file (certreq.csr in the example).
You can do this by either of the following methods:
Have the certificate signed by a well known certification authority (CA), such as Thawte or Verisign. See your CA’s documentation for more information on how to do this.
Sign the certificate yourself, using an SSL signing software package.
The resulting signed certificate is a sequence of ASCII characters. If you receive the signed certificate from a CA, it may arrive as an e-mail attachment or in the text of a message.
The instructions below use the example name broker.cer to represent the broker certificate.
The following command lists the root CAs in the system key store:keytool -v -list -keystore $JAVA_HOME/lib/security/cacerts
If your CA is listed, skip the next step.
Here is an example:keytool -import -alias ca -file ca.cer -noprompt -trustcacerts -keystore /etc/imq/keystore -storepass myStorePassword
where ca.cer is the file containing the root certificate obtained from the CA.
If you are using a CA test certificate, you probably need to import the test CA root certificate. Your CA should have instructions on how to obtain a copy.
Here is an example:keytool -import -alias imq -file broker.cer -noprompt -trustcacerts -keystore /etc/imq/keystore -storepass myStorePassword
where broker.cer is the file containing the signed certificate that you received from the CA.
The Message Queue key store now contains a signed certificate to use for SSL connections.
You must now configure the Message Queue client runtime to require signed certificates, and ensure that it trusts the certification authority that signed the certificate.
Note - By default, starting with release 4.0, the connection factory object that the client will be using to establish broker connections has its imqSSLIsHostTrusted attribute set to false, meaning that the client runtime will attempt to validate all certificates. Validation will fail if the signer of the certificate is not in the client's trust store.
To test whether the client will accept certificates signed by your certification authority, try to establish an SSL connection, as described above under Configuring and Running an SSL-Based Client Using Self-Signed Certificates. If the CA is in the client's trust store, the connection will succeed and you can skip the next step. If the connection fails with a certificate validation error, go on to the next step.
The client searches the key store files cacerts and jssecacerts by default, so no further configuration is necessary if you install the certificate in either of those files. The following example installs a test root certificate from the Verisign certification authority from a file named testrootca.cer into the default system certificate file, cacerts. The example assumes that J2SE is installed in the directory $JAVA_HOME/usr/j2se:keytool -import -keystore /usr/j2se/jre/lib/security/cacerts -alias VerisignTestCA -file testrootca.cer -noprompt -trustcacerts -storepass myStorePassword
An alternative (and recommended) option is to install the root certificate into the alternative system certificate file, jssecacerts:keytool -import -keystore /usr/j2se/jre/lib/security/jssecacerts -alias VerisignTestCA -file testrootca.cer -noprompt -trustcacerts -storepass myStorePassword
A third possibility is to install the root certificate into some other key store file and configure the client to use that as its trust store. The following example installs into the file /home/smith/.keystore:keytool -import -keystore /home/smith/.keystore -alias VerisignTestCA -file testrootca.cer -noprompt -trustcacerts -storepass myStorePassword
Since the client does not search this key store by default, you must explicitly provide its location to the client to use as a trust store. You do this by setting the Java system property javax.net.ssl.trustStore once the client is running:javax.net.ssl.trustStore=/home/smith/.keystore