This section explains how to set up a connection service based on the Secure Socket Layer (SSL) standard, which sends encrypted messages between clients and broker. Message Queue supports the following SSL-based connection services:
The ssljms service delivers secure, encrypted messages between a client and a broker, using the TCP/IP transport protocol.
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).
The cluster service provides secure, encrypted communication between brokers in a cluster, using the TCP/IP transport protocol.
The httpsjms service delivers secure, encrypted messages between a client and a broker, using an HTTPS tunnel servlet with the HTTP transport protocol.
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 steps described in this section and then follow them with the additional ones 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. The following procedure shows the steps needed to set up an SSL-based connection service to use self-signed certificates. The subsections that follow describe each of these steps in greater detail.
Generate a self-signed certificate.
Enable the ssljms, ssladmin, or cluster connection service in the broker.
Start the broker.
Configure and run the client.
This step applies only to the ssljms connection service and not to ssladmin or cluster.
Run the Key Tool utility (imqkeytool) to generate a self-signed certificate for the broker. (On UNIX® systems, you may need to run the utility as the superuser (root) in order to have permission to create the key store.) The same certificate can be used for the ssljms, ssladmin, or cluster connection service.
Enter the following at the command prompt:
imqkeytool -broker
The Key Tool utility prompts you for a key store password:
Generating keystore for the broker ... Enter keystore password:
Next, the utility prompts you for information identifying the broker to which this certificate belongs. The information you supply will make up an X.500 distinguished name. Table 7–5 shows the prompts and the values to be provided for each. Values are case-insensitive and can include spaces.
Table 7–5 Distinguished Name Information Required for a Self-Signed Certificate
Prompt |
X.500 Attribute |
Description |
Example |
---|---|---|---|
What is your first and last name? |
commonName (CN) |
Fully qualified name of server running the broker |
mqserver.sun.com |
What is the name of your organizational unit? |
organizationalUnit (OU) |
Name of department or division |
purchasing |
What is the name of your organization? |
organizationName (ON) |
Name of larger organization, such as a company or government entity |
My Company, Inc. |
What is the name of your city or locality? |
localityName (L) |
Name of city or locality |
San Francisco |
What is the name of your state or province? |
stateName (ST) |
Full (unabbreviated) name of state or province |
California |
What is the two-letter country code for this unit? |
country (C) |
Standard two-letter country code |
US |
When you have entered the information, the Key Tool utility displays it for confirmation. For example:
Is CN=mqserver.sun.com, OU=purchasing, ON=My Company, Inc., L=San Francisco, ST=California, C=US correct?
To accept the current values and proceed, enter yes; to reenter values, accept the default or enter no. After you confirm, the utility pauses while it generates a key pair.
Next, the utility asks for a password to lock the key pair (key password). Press Return in response to this prompt to use the same password as the key password and key store password.
Remember the password you specify. You must provide this password when you start the broker, to allow the broker to open the key store. You can store the key store password in a password file (see Password Files).
The Key Tool utility generates a self-signed certificate and places it in Message Queue’s key store. The key store is located in a directory that depends upon the operating system, as shown in Appendix A, Platform-Specific Locations of Message QueueTM Data.
The following are the configurable properties for the Message Queue key store for SSL-based connection services:
imq.keystore.file.dirpath: The path to the directory containing the key store file. For the default value, see Appendix A, Platform-Specific Locations of Message QueueTM Data.
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 key store password when you generated the self-signed certificate.)
Remove the broker’s key store, located as shown in Appendix A, Platform-Specific Locations of Message QueueTM Data.
Run imqkeytool again to generate a new key pair, as described above.
To enable an SSL-based connection service in the broker, you need to add ssljms (or ssladmin) to the imq.service.activelist property.
Open the broker’s instance configuration file.
The instance configuration file is located in a directory identified by the name of the broker instance (instanceName) with which the configuration file is associated (see Appendix A, Platform-Specific Locations of Message QueueTM Data):
.../instances/instanceName/props/config.properties
Add an entry (if one does not already exist) for the imq.service.activelist property and include the desired SSL-based service(s) in the list.
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
The SSL-based cluster connection service is enabled using the imq.cluster.transport property rather than the imq.service.activelist property; see Connecting Brokers.
Save and close the instance configuration file.
Start the broker, providing the key store password. You can provide the password in either of two ways:
Allow the broker to prompt you for the password when it starts up:
imqbrokerd Please enter Keystore password:
Put the password in a password file, as described in Password Files. Then set the property imq.passfile.enabled = true and do one of the following:
Pass the location of the password file to the imqbrokerd command:
imqbrokerd -passfile /passfileDirectory/passfileName
Start the broker without the -passfile option, but specify the location of the password file using the following two broker configuration properties:
imq.passfile.dirpath=/passfileDirectoryimq.passfile.name=passfileName
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.
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:
imq.jar
jms.jar
If you are using a version of the Java 2 Software Development Kit (J2SDK) earlier than 1.4, you must also include the following Java Secure Socket Extension (JSSE) and Java Naming and Directory Interface (JNDI) .jar files:
jsse.jar
jnet.jar
jcert.jar
jndi.jar
(It is not necessary to include these files if you are using J2SDK 1.4 or later, which has JSSE and JNDI support built in.)
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 adminName -secure
where adminName is a valid entry in the Message Queue user repository. The command will prompt you for the password. (If you are using a flat-file repository, see Changing the Default Administrator 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 the following output:
Listing all the services on the broker specified by: Host Primary Port localhost 7676 Service Name Port Number Service State admin 33984 (dynamic) RUNNING httpjms - UNKNOWN httpsjms - UNKNOWN jms 33983 (dynamic) RUNNING ssladmin 35988 (dynamic) RUNNING ssljms dynamic UNKNOWN Successfully listed services. |
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 not between multiple brokers in a cluster. This requires the following extra steps in addition to the ones described above for configuring self-signed certificates. These steps are described in greater detail in the subsections that follow.
Install the certificate in the key store.
Configure the Message Queue client to require signed certificates when establishing an SSL-based connection to the broker.
The following procedures explain how to obtain and install a signed certificate.
Use the J2SE keytool command to generate a certificate signing request (CSR) for the self-signed certificate you generated in the preceding section.
Information about the keytool command can be found at
http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html
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).
Use the CSRto generate or request a signed certificate.
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.
Save the signed certificate in a file.
The instructions below use the example name broker.cer to represent the broker certificate.
Check whether J2SE supports your certification authority by default.
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.
If your certification authority is not supported in J2SE, import the CA’s root certificate into the Message Queue key store.
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.
Import the signed certificate into the key store to replace the original self-signed certificate.
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.
Set the connection factory's imqSSLIsHostTrusted attribute to false.
By default, the imqSSLIsHostTrusted attribute of the connection factory object that the client will be using to establish broker connections is set to true, meaning that the client runtime will accept any certificate presented to it. You must change this value to false so that the client runtime will attempt to validate all certificates presented to it. Validation will fail if the signer of the certificate is not in the client's trust store.
Verify whether the signing authority is registered 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.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.
Install the signing CA’s root certificate in the client’s trust store.
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