Sun Java System Message Queue 4.3 Administration Guide

Setting Up an SSL-Based Connection Service Using Self-Signed Certificates

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.

  1. Generate a self-signed certificate.

  2. Enable the desired SSL-based connection services in the broker. These can include the ssljms, ssladmin, or cluster connection services.

  3. Start the broker.

ProcedureTo Generate a Self-Signed Certificate

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).

  1. Enter the following at the command prompt:

    imqkeytool -broker

    The Key Tool utility prompts you for a key store password:

  2. At the prompt type a keystore 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.


    X.500 Attribute 



    What is your first and last name?

    commonName (CN)

    Fully qualified name of server running the broker

    What is the name of your organizational unit?

    organizationalUnit (OU)

    Name of department or division 


    What is the name of your organization?

    organizationName (ON)

    Name of larger organization, such as a company or government entity 

    Acme Widgets, 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 


    What is the two-letter country code for this unit?

    country (C)

    Standard two-letter country code 


    The Key Tool utility displays the information you entered for confirmation. For example,

       Is, OU=purchasing, ON=Acme Widgets, Inc.,
       L=San Francisco, ST=California, C=US correct?
  3. Accept the current values and proceed by typing yes.

    To reenter values, accept the default or enter no. After you confirm, the utility pauses while it generates a key pair.

    The utility asks for a password to lock the key pair (key password).

  4. Press return.

    This will set the same password for both the key password and the keystore password.

    Caution – 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 a directory whose location depends upon the operating system platform, as shown in Appendix A, Platform-Specific Locations of Message Queue Data.

    The following are the configurable properties for the Message Queue keystore for SSL-based connection services:


    Path to directory containing keystore file (see Appendix A, Platform-Specific Locations of Message Queue Data for default value)

    Name of key store file


    Ke store password (to be used only in a password file)

    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: 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.)

ProcedureTo Regenerate a Key Pair

  1. Remove the broker’s keystore file.

    The file is located as shown in Appendix A, Platform-Specific Locations of Message Queue Data.

  2. Run imqkeytool again.

    The command will generate a new key pair, as described above.

ProcedureTo Enable an SSL-Based Connection Service in the Broker

To enable an SSL-based connection service in the broker, you need to add the corresponding service or services to the imq.service.activelist property.

  1. 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 Queue Data):

  2. 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):


    Note –

    The SSL-based cluster connection service is enabled using the imq.cluster.transport property rather than the imq.service.activelist property (see Cluster Connection Service Properties). To enable SSL for RMI-based JMX connectors, see SSL-Based JMX Connections.

  3. Save and close the instance configuration file.

ProcedureTo Start the Broker

Start the broker, providing the key store password.

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, 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.

  1. Start the broker, providing the keystore password.

    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:

    • 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:


  2. If you are not using a password file, enter the keystore password at the prompt.


    You are prompted for the keystore passwrd.