Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Message Queue 3 2005Q1 Administration Guide 

Chapter 7
Managing Security

As administrator, you configure a user repository for use in authenticating users; define access control; configure a Secure Socket Layer (SSL) connection service that encrypts client-broker communication; and set up a passfile for use in broker startup.

The chapter includes the following sections:

Authenticating Users

You are responsible for maintaining a list of users, their groups, and their passwords in a user repository. You can use a different user repository for each broker instance. This section explains how you create, populate, and manage that repository.

When a user attempts to connect to the broker, the broker authenticates the user by inspecting the name and password provided. The broker grants the connection if the name and password match those in a broker-specific user repository that each broker is configured to consult.

The repository can be one of the following types:

Using a Flat-File User Repository

Message Queue provides a flat-file user repository and a command line tool, Message Queue User Manager (imqusermgr) that you can use to populate and manage the flat-file user repository. The following sections describe the flat-file user repository and how you use the Message Queue User Manager utility (imqusermgr) to populate and manage that repository.

Creating a User Repository

The flat-file user repository is instance specific. A default user repository (named passwd) is created for each broker instance that you start. This user repository is placed in a directory identified by the name of the broker instance with which the repository is associated (see Appendix A, "Operating System-Specific Locations of Message Queue Data"):


The repository is created with two entries (rows), as illustrated in Table 7-1, below.

Table 7-1  Initial Entries in User Repository 

User Name












These initial entries allow the Message Queue broker to be used immediately after installation without intervention by the administrator. Initial user/password setup is not required for the Message Queue broker to be used.

The initial guest user entry allows clients to connect to a broker instance using the default guest user name and password (for testing purposes, for example).

The initial admin user entry lets you use imqcmd commands to administer a broker instance using the default admin user name and password. You should update this initial entry to change the password (see Changing the Default Administrator Password).

The following sections explain how you populate and manage a flat-file user repository.

User Manager Utility (imqusermgr)

The User Manager utility (imqusermgr) lets you edit or populate a flat-file user repository. This section introduces the User Manager utility. Subsequent sections explain how you use the imqusermgr subcommands to accomplish specific tasks.

For full reference information about the imqusermgr command, see Chapter 13, "Command Reference."

Before using imqusermgr, keep the following things in mind:


The imqusermgr command has the subcommands add, delete, list, and update.

add Subcommand     The add subcommand adds a user and associated password to the specified (or default) broker instance repository, and optionally specifies the user’s group. The subcommand syntax is as follows:

add [-i instanceName] -u userName -p passwd [-g group] [-s]

delete Subcommand     The delete subcommand deletes the specified user from the specified (or default) broker instance repository. The subcommand syntax is as follows:

delete [-i instanceName] -u userName [-s] [-f]

list Subcommand     The list subcommand displays information about the specified user or all users in the specified (or default) broker instance repository. The subcommand syntax is as follows:

list [-i instanceName] [-u userName]

update Subcommand     The update subcommand updates the password and/or state of the specified user in the specified (or default) broker instance repository. The subcommand syntax is as follows:

update [-i instanceName] -u userName -p passwd [-a state] [-s] [-f]

update [-i instanceName] -u userName -a state [-p passwd] [-s] [-f]

Command Options

Table 7-2 lists the options to the imqusermgr command.

Table 7-2  imqusermgr Options  



-a active_state

Specifies (true/false) whether the user’s state should be active. A value of true means that the state is active. This is the default.


Performs action without user confirmation


Displays usage help. Nothing else on the command line is executed.

-i instanceName

Specifies the broker instance user repository to which the command applies. If not specified, the default instance name, imqbroker, is assumed.

-p passwd

Specifies the user’s password.

-g group

Specifies the user group. Valid values are admin, user, anonymous.


Sets silent mode.

-u userName

Specifies the user name.


Displays version information. Nothing else on the command line is executed.


When adding a user entry to the user repository for a broker instance, you can specify one of three predefined groups: admin, user, or anonymous. If no group is specified, the default group user is assigned.

To change a user’s group, you must delete the user entry and then add another entry for the user, specifying the new group.

You cannot rename or delete these system-created groups, or create new groups. However, you can specify access rules that define the operations that the members of that group can perform. For more information, see Authorizing Users: the Access Control Properties File.

User States

When you add a user to a repository, the user’s state is active by default. To make the user inactive, you must use the update command. For example, the following command makes the user JoeD inactive:

imqusermgr update -u JoeD -a false

Entries for users that have been rendered inactive are retained in the repository; however, inactive users cannot open new connections. If a user is inactive and you add another user who has the same name, the operation will fail. You must delete the inactive user entry or change the new user’s name or use a different name for the new user. This prevents you from adding duplicate user names.

Format of User Names and Passwords

User names and passwords must follow these guidelines:

Populating and Managing a User Repository

Use the add subcommand to add a user to a repository. For example, the following command adds the user Katharine with the password sesame to the default broker instance user repository.

imqusermgr add -u Katharine -p sesame -g user

Use the delete subcommand to delete a user from a repository. For example, the following command deletes the user, Bob:

imqusermgr delete -u Bob

Use the update subcommand to change a user’s password or state. For example, the following command changes Katharine’s password to aladdin:

imqusermgr update -u Katharine -p aladdin

To list information about one user or all users, use the list command. The following command shows information about the user named isa:

imqusermgr list -u isa

% imqusermgr list -u isa

User repository for broker instance: imqbroker


User Name    Group    Active State


isa          admin    true

The following command lists information about all users:

imqusermgr list

% imqusermgr list

User repository for broker instance: imqbroker


User Name    Group        Active State


admin        admin        true

guest        anonymous    true

isa          admin        true

testuser1    user         true

testuser2    user         true

testuser3    user         true

testuser4    user         false

testuser5    user         false

Changing the Default Administrator Password

For the sake of security, you should change the default password of admin to one that is only known to you. You need to use the imqusermgr tool to do this.

The following command changes the default administrator password for the mybroker broker instance from admin to grandpoobah.

imqusermgr update mybroker -u admin -p grandpoobah

You can quickly confirm that this change is in effect by running any of the command line tools when the broker instance is running. For example, the following command will prompt you for a password:

imqcmd list svc mybroker -u admin

Entering the new password (grandpoobah) should work; the old password should fail.

After changing the password, you should supply the new password any time you use any of the Message Queue administration tools, including the Administration Console.

Using an LDAP Server for a User Repository

To use an LDAP server for a user repository, you perform the following tasks:

Editing the Instance Configuration File

To have a broker use a directory server, you set the values for certain properties in the broker instance configuration file, These properties enable the broker instance to query the LDAP server for information about users and groups. The broker queries the LDAP server whenever a user attempts to connect to the broker instance or perform certain messaging operations.

The instance configuration file is located in a directory under the broker instance directory. The path has the following format:


For information about the operating system-specific location of instance directories, see Appendix A, "Operating System-Specific Locations of Message Queue Data."

    To Edit the Configuration File to Use an LDAP Server
  1. Specify that you are using an LDAP user repository by setting the following property:
  2. imq.authentication.basic.user_repository=ldap

  3. Set the imq.authentication.type property to determine whether a password should be passed from client to broker in base64 encoding (basic) or in MD5 digest (digest). When using an LDAP directory server for a user repository, you must set the authentication type to basic. For example,
  4. imq.authentication.type=basic

  5. You must also set the broker properties that control LDAP access. These properties are stored in a broker’s instance configuration file. The properties are described in and summarized later in this section.
  6. Message Queue uses JNDI APIs to communicate with the LDAP directory server. Consult JNDI documentation for more information on syntax and on terms referenced in these properties. Message Queue uses a Sun JNDI LDAP provider and uses simple authentication.

    Message Queue supports LDAP authentication failover: you can specify a list of LDAP directory servers for which authentication will be attempted (see the reference information for the imq.user.repos.ldap.server property).

    See the broker’s file for a sample of how to set properties related to LDAP user-repository.

  7. If necessary, you need to edit the users/groups and rules in the access control properties file. For more information about the use of access control property files, see Authorizing Users: the Access Control Properties File.
  8. If you want the broker to communicate with the LDAP directory server over SSL during connection authentication and group searches, you need to activate SSL in the LDAP server and then set the following properties in the broker configuration file:
    • Specify the port used by the LDAP server for SSL communications. For example:
    •   imq.user_repository.ldap.server=myhost:7878

    • Set the broker property imq.user_repository.ldap.ssl.enabled
      to true.

These are the LDAP-related properties:

For full reference information about these properties, see Security Manager Properties.

Setting Up Access Control for Administrators

To create administrative users, you use the access control properties file to specify users and groups that can create ADMIN connections. These users and groups must be predefined in the LDAP directory.

Any user or group who can create an ADMIN connection can issue administrative commands.

    To Set Up an Administrative User
  1. Enable the use of the access control file by setting the broker property imq.accesscontrol.enabled to true, which is the default value.
  2. The imq.accesscontrol.enabled property enables use of the access control file.

  3. Open the access control file, The location for the file is listed in Appendix A, "Operating System-Specific Locations of Message Queue Data."
  4. The file contains an entry such as the following:

    service connection access control

    The entries listed are examples. Note that the admin group exists in the file-based user repository but does not exist by default in the LDAP directory. You must substitute the name of a group that is defined in the LDAP directory, to which you want to grant Message Queue administrator privileges.

  5. To grant Message Queue administrator privileges to users, enter the user names as follows:
  6. connection.ADMIN.allow.user=userName[,userName2,..]

  7. To grant Message Queue administrator privileges to groups, enter the group names as follows:

Authorizing Users: the Access Control Properties File

An access control properties file (ACL file) contains rules that specify the operations that users and groups of users can perform. You edit the ACL file to restrict operations to certain users and groups. You can use a different ACL file for each broker instance.

A broker checks its ACL file when a client application performs one of the following operations:

The broker checks the ACL file to determine whether the user that generated the request, or a group to which the user belongs, is authorized to perform the operation.

If you edit an ACL file, the new settings take effect the next time that the broker checks the file to verify authorization. You need not restart the broker after editing the file.

The ACL file is used whether user information is placed in a flat-file user repository (see Using a Flat-File User Repository) or in an LDAP user repository (see Using an LDAP Server for a User Repository).

Creating an Access Control Properties File

The ACL file is instance specific. Each time you start a broker instance, a default file named is created in the instance directory. The path to the file has the following format (see Appendix A, "Operating System-Specific Locations of Message Queue Data"):


The ACL file is formatted like a Java properties file. It starts by defining the version of the file and then specifies access control rules in three sections:

The version property defines the version of the ACL properties file; you may not change this entry.


The three sections of the ACL file that specify access control are described below, following a description of the basic syntax of access rules and an explanation of how permissions are calculated.

Syntax of Access Rules

In the ACL properties file, access control defines what access specific users or groups have to protected resources like physical destinations and connection services. Access control is expressed by a rule or set of rules, with each rule presented as a Java property:

The basic syntax of these rules is as follows:

resourceType.resourceVariant.operation.access.principalType = principals

Table 7-3 describes the elements of syntax rules.

Table 7-3  Syntactic Elements of Access Rules 




One of the following: connection, queue or topic.


An instance of the type specified by resourceType. For example, myQueue. The wild card character (*) may be used to mean all connection service types or all physical destinations.


Value depends on the kind of access rule being formulated.


One of the following: allow or deny.


One of the following: user or group. For more information, see Groups.


Who may have the access specified on the left-hand side of the rule. This may be an individual user or a list of users (comma delimited) if the principalType is user; it may be a single group or a list of groups (comma delimited list) if the principalType is group. The wild card character (*) may be used to represent all users or all groups.

Here are some examples of access rules:

How Permissions are Computed

When there are multiple access rules in the file, permissions are computed as follows:

Access Control for Connection Services

The connection access control section in the ACL properties file contains access control rules for the broker’s connection services. The syntax of connection access control rules is as follows:

connection.resourceVariant.access.principalType = principals

Two values are defined for resourceVariant: NORMAL and ADMIN. These predefined values are the only types of connection services to which you can grant access.

The default ACL properties file gives all users access to NORMAL connection services and gives users in the group admin access to ADMIN connection services:


If you are using a file-based user repository, the default group admin is created by imqusermgr. If you are using an LDAP user repository, you can do one of the following to use the default ACL properties file:

You can restrict connection access privileges. For example, the following rules deny Bob access to NORMAL but allow everyone else:



You can use the asterisk (*) character to specify all authenticated users or groups.

The way that you use the ACL properties file to grant access to ADMIN connections differs for file-based user repositories and LDAP user repositories, as follows:

Access Control for Physical Destinations

The destination access control section of the access control properties file contains physical destination-based access control rules. These rules determine who (users/groups) may do what (operations) where (physical destinations). The types of access that are regulated by these rules include sending messages to a queue, publishing messages to a topic, receiving messages from a queue, subscribing to a topic, and browsing a messages in a queue.

By default, any user or group can have all types of access to any physical destination. You can add more specific destination access rules or edit the default rules. The rest of this section explains the syntax of physical destination access rules, which you must understand to write your own rules.

The syntax of destination rules is as follows:

resourceType.resourceVariant.operation.access.principalType = principals

Table 7-4 describes these elements:

Table 7-4  Elements of Physical Destination Access Control Rules 




Can be queue or topic.


A physical destination name or all physical destinations (*), meaning all queues or all topics.


Can be produce, consume, or browse.


Can be allow or deny.


Can be user or group.

Access can be given to one or more users and/or one or more groups.

The following examples illustrate different kinds of physical destination access control rules:

Access Control for Auto-created Physical Destinations

The final section of the ACL properties file, includes access rules that specify for which users and groups the broker will auto-create a physical destination.

When a user creates a producer or consumer at a physical destination that does not already exist, the broker will create the destination if the broker’s auto-create property has been enabled.

By default, any user or group has the privilege of having a physical destination auto-created by the broker. This privilege is specified by the following rules:



You can edit the ACL file to restrict this type of access.

The general syntax for physical destination auto-create access rules is as follows:

resourceType.create.access.principalType = principals

Where resourceType is either queue or topic.

For example, the following rules allow the broker to auto-create topic destinations for everyone except Snoopy.



Note that the effect of physical destination auto-create rules must be congruent with that of physical destination access rules. For example, if you 1) change the destination access rule to forbid any user from sending a message to a destination but 2) enable the auto-creation of the destination, the broker will create the physical destination if it does not exist but it will not deliver a message to it.

Working With an SSL-Based Service

A connection service that is based on the Secure Socket Layer (SSL) standard sends encrypted messages sent between clients and broker. This section explains how to set up an SSL-based connection service.

Message Queue supports the following connection services that are based on the Secure Socket Layer (SSL) standard:

These connection services allow for the encryption of messages sent between clients and broker. Message Queue supports SSL encryption based on either self-signed server certificates or signed certificates.

To use an SSL-based connection service, you generate a private key/public 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.

While Message Queue’s SSL-based connection services are similar in concept, there are some differences in how you set them up.

The rest of this section describes how to set up secure connections over TCP/IP.

The SSL-based connection service for user over HTTP, httpsjms, lets a client and broker establish a secure connection by way of an HTTPS tunnel servlet. For information on setting up secure connections over HTTP, see Appendix C, "HTTP/HTTPS Support".

Secure Connection Services for TCP/IP

The following SSL-based connection services provide a direct, secure connection over TCP/IP:

Configuring the Use of Self-Signed Certificates

This section describes how to set up an SSL-based service using self-signed certificates.

For a stronger level of authentication, you can use signed certificates that are verified by a certificate authority. First follow the steps in this section and then go to Configuring the Use of Signed Certificates to perform additional steps.

    To Set Up an SSL-based Connection Service
  1. Generate a self-signed certificate.
  2. Enable the ssljms, ssladmin, or cluster connection service in the broker.
  3. Start the broker.
  4. Configure and run the client (applies only to ssljms connection service).

The procedures for setting up ssljms and ssladmin connection services are identical, except for Step 4, configuring and running the client.

Each of the steps is discussed in some detail in the sections that follow.

Step 1. Generating a Self-Signed Certificate

Message Queue SSL support with self-signed certificates is oriented toward securing on-the-wire data with the assumption that the client is communicating with a known and trusted server.

Run the imqkeytool command to generate a self-signed certificate for the broker. On UNIX® systems you may need to run imqkeytool as the superuser (root) in order to have permission to create the keystore.

The same certificate can be used for the ssljms, ssladmin, or cluster connection service.

Enter the following at the command prompt:

imqkeytool -broker

The utility prompts you for a keystore password.

Generating keystore for the broker ...
Enter keystore password:

Next, the utility prompts for information that identifies the broker whose certificate this is. The information that you supply will make up an X.500 distinguished name. The following table lists the prompts, describes them, and provides an example for each prompt. Values are case-insensitive and can include spaces.

Table 7-5  Distinguished Name Information Required for a Self-Signed Certificate




What is your first and last name?

The X.500 commonName (CN). Enter the fully qualified name of the server that is running the broker.

What is the name of your organizational unit?

The X.500 organizationalUnit (OU). Enter the name of a department or division.


What is the name of your organization?

The X.500 organizationName (ON). Name of a larger organization, such as a company or government entity.

My Company, Inc.

What is the name of your city or locality?

The X.500 localityName (L).

San Francisco

What is the name of your state or province?

The X.500 stateName (ST). Enter the full name of the state or province, without abbreviating.


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

The X.500 country (C).


When you have entered the information, imqkeytool displays it for confirmation. For example:

Is, OU=purchasing, O=My Company, Inc., L=San Francisco, ST=California, C=US correct?

To re-enter values, accept the default or enter no; to accept the current values and proceed, enter yes. After you confirm, imqkeytool pauses while it generates a key pair.

Next, imqkeytool asks for a password to lock the particular key pair (key password). Enter Return in response to this prompt to use the same password as the key password and keystore password.


Remember the password you provide. You must provide this password when you start the broker, to allow the broker to open the keystore. You can store the keystore password in a passfile (see Using a Passfile).

Running imqkeytool runs the JDK keytool utility to generate a self-signed certificate and places it in Message Queue’s keystore, located in a directory that depends upon the operating system, as shown in Appendix A, "Operating System-Specific Locations of Message Queue Data."

The keystore is in the same format as that supported by the JDK1.2 keytool utility.

These are the configurable properties for the Message Queue keystore:

You might need to regenerate a key pair in order to solve certain problems; for example:

    To Regenerate a Key Pair
  1. Remove the broker’s keystore, located as shown in Appendix A, "Operating System-Specific Locations of Message Queue Data."
  2. Rerun imqkeytool to generate a key pair as described in Step 1. Generating a Self-Signed Certificate.

Step 2. Enabling the SSL-Based Service in the Broker

To enable the SSL-based service in the broker, you need to add ssljms (or ssladmin) to the imq.service.activelist property.


The SSL-based cluster connection service is enabled using the imq.cluster.transport property rather than the imq.service.activelist property. See Secure Connections Between Brokers.

    To Enable an SSL-based Service in the Broker
  1. Open the broker’s instance configuration file.
  2. 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, "Operating System-Specific Locations of Message Queue Data"):


  3. Add an entry (if one does not already exist) for the imq.service.activelist property and include SSL-based services in the list.
  4. By default, the property includes the jms and admin connection services. You need to add the ssljms or ssladmin connection services or both (depending on the services you want to activate):


Step 3. Starting the Broker

Start the broker, providing the keystore password. You can provide the password in any one of the following ways:

When you start a broker or client with SSL, you might notice that it consumes a lot of cpu cycles for a few seconds. This is because Message Queue uses JSSE (Java Secure Socket Extension) to implement SSL. JSSE uses to generate random numbers. This method takes a significant amount of time to create the initial random number seed, and that is why you are seeing increased cpu usage. After the seed is created, the cpu level will drop to normal.

Step 4. Configuring and Running SSL-Based Clients

Finally, you configure clients to use the secure connection services. There are two types of secure connection scenarios over TCP/IP:

These are treated separately in the following sections.

Application Clients Using ssljms

You must make sure the client has the necessary Secure Socket Extension (JSSE) jar files in its classpath, and you need to tell it to use the ssljms connection service.

  1. If your client is not using J2SDK1.4 (which has JSSE and JNDI support built in), make sure the client has the following jar files in its class path:
  2. jsse.jar, jnet.jar, jcert.jar, jndi.jar

  3. Make sure the client has the following Message Queue jar files in its class path:
  4. imq.jar, jms.jar

  5. Start the client and connect to the broker’s ssljms service. One way to do this is by entering a command like the following:
  6. java -DimqConnectionType=TLS clientAppName

    Setting imqConnectionType tells the connection to use SSL.

    For more information on using ssljms connection services in client applications, see the chapter on using administered objects in the Message Queue Developer’s Guide for Java Clients.

Administration Clients (imqcmd) Using ssladmin

You can establish a secure administration connection by including the -secure option when using imqcmd. For example:

imqcmd list svc -b hostName:port -u adminName -secure

where adminName is a valid entry in the Message Queue user repository and the command will prompt 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 show that the ssladmin service is running, and that you can successfully make a secure admin 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.

Configuring the Use of Signed Certificates

Signed certificates provide a stronger level of server authentication than self-signed certificates. To implement signed certificates, you install a signed certificate into the keystore, and then configure the Message Queue client so that it requires a signed certificate when it establishes an SSL connection to imqbrokerd.

You can implement signed certificates only between client and broker, and not between multiple brokers in a cluster.

The instructions that follow assume that you have already performed the steps documented under Configuring the Use of Self-Signed Certificates. While you are following the instructions, it might be helpful to have access to the information about J2SE keytool and X.509 certificates at

Step 1: Obtaining and Installing a Signed Certificate

    To Obtain a Signed Certificate
  1. Use the J2SE keytool to generate a Certificate Signing Request (CSR) for the self-signed certificate you just generated.
  2. Here is an example:

    keytool -certreq -keyalg RSA -alias imq -file certreq.csr
            -keystore /etc/imq/keystore -storepass myStorePassword

    The CSR now encapsulates the certificate in the file certreq.csr.

  3. Generate or request a signed certificate by one of the following methods:
    • Have the certificate signed by a well known certificate authority (CA), such as Thawte or Verisign. See your CA’s documentation for more information on this process.
    • Sign the certificate yourself by 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 might arrive as an email attachment or in the text of a message.

  4. When you get the signed certificate, save it in a file.
  5. These instructions use the example name broker.cer to represent the broker certificate.

    To Install a Signed Certificate
  1. Check $JAVA_HOME/lib/security/cacerts to find out whether J2SE supports your CA by default, as follows:
  2. keytool -v -list -keystore $JAVA_HOME/lib/security/cacerts

    The command lists the root CAs in the system keystore.

    If your CA is listed, skip the next step.

  3. If your CA is not supported in J2SE, import the certificate authority’s root certificate into the imqbrokerd keystore.
  4. Here is an example:

    keytool -import -alias ca -file ca.cer -noprompt -trustcacerts
            -keystore /etc/imq/keystore -storepass myStorePassword

    The ca.cer value is the CA 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 of the Test CA Root.

  5. Import the signed certificate into the keystore to replace the original self-signed certificate.
  6. For example:

    keytool -import -alias imq -file broker.cer -noprompt -trustcacerts
            -keystore /etc/imq/keystore -storepass myStorePassword

    The broker.cer value is the file that contains the signed certificate that you received from the CA.

The imqbrokerd keystore now has a signed certificate to use for SSL connections.

Step 2: Configuring the Client Runtime to Require a Signed Certificate

    To Configure the Java Client Runtime

By default, the Message Queue client runtime trusts imqbrokerd and accepts any certificate that is presented to it. You must now configure the client runtime to require signed certificates, and ensure that the client trusts the CA that signed the certificate.

  1. To configure the client to require a valid, signed certificate from imqbrokerd, set the imqSSLIsHostTrusted attribute to false for the client’s ConnectionFactory object.
  2. Try to establish an SSL connection to imqbrokrd, as described under Step 4. Configuring and Running SSL-Based Clients.
  3. If the broker’s certificate was signed by a well-known CA, the connection will probably succeed and you can skip the next step. If the connection fails with a certificate validation error, perform the next step.

  4. Install the signing CA's root certificate in the client's truststore, as described in the following sections.

There are three options for configuring the client with a truststore:

The following sections contain examples of how to install a Verisign Test Root CA using these options. The root CA is contained in a file called testrootca.cer. The examples assume that J2SE is installed in /usr/j2se.

Installing into the Default System cacerts File

This example installs the root CA into the file $JAVA_HOME/usr/jre/lib/security/cacerts.

keytool -import -keystore /usr/j2se/jre/lib/security/cacerts
         -alias VerisignTestCA -file testrootca.cer -noprompt          -trustcacerts -storepass

The client searches this keystore by default, so no further client configuration is necessary.

Installing into jssecacerts

This example installs the root CA into the file $JAVA_HOME/usr/jre/lib/security/jssecacerts.

keytool -import -keystore /usr/j2se/jre/lib/security/jssecacerts
         -alias VerisignTestCA -file testrootca.cer -noprompt
         -trustcacerts -storepass myStorePassword

The client searches this keystore by default, so no further client configuration is necessary.

Installing into Other Files

This example installs the root CA into the file /home/smith/.keystore.

keytool -import -keystore /home/smith/.keystore
         -alias VerisignTestCA -file testrootca.cer -noprompt          -trustcacerts -storepass myStorePassword

The client does not search this keystore by default, so you must provide the location of the truststore to the client. To do so, set the Java system property once the client is running. For example:

Using a Passfile

Several types of commands require passwords. In Table 7-6, the first column lists the commands that require passwords and the second column lists the reason that passwords are needed.

Table 7-6  Commands That Use Passwords



Purpose of Password


Starts the broker

Access a plugged-in persistent data store, an SSL certificate keystore, or an LDAP user repository


Manages the broker

Authenticate an administrative user who is authorized to use the command


Manages a plugged-in data store

Access the data store

You can specify these passwords in a password file (passfile) and use the -passfile option to specify the name of the file. This is the format for the -passfile option:

imqbrokerd -passfile myPassfile


In previous releases, you could use the -p, -password, -dbpassword, and -ldappassword options to specify passwords on a command line. These options are deprecated and will be removed in a future release. In this release, a value on the command line for one of these options supersedes the associated value in a password file.

Security Concerns

Specifying a password interactively, in response to a prompt, is the most secure method of specifying a password, unless your monitor is visible to other people. You can also specify a passfile on the command line. For non-interactive use of commands, however, you must use a passfile.

A passfile is unencrypted, so you must set its permissions to protect it from unauthorized access. Set permissions such that they limit the users who can view the file, but provide read access to the user who starts the broker.

Passfile Contents

A passfile is a simple text file that contains a set of properties and values. Each value is a password used by a command.

A passfile can contain the passwords shown in Table 7-7:

Table 7-7  Passwords in a Passfile


Affected Commands




Specifies the administrator password for an imqcmd command line. The password is authenticated for each command.



Specifies the keystore password for SSL-based services.




Specifies the password used to open a database connection, if required.



Specifies the password associated with the distinguished name assigned to a broker for binding to a configured LDAP user repository.

A sample passfile is part of the Message Queue product. For the location of the sample file, see Appendix A, "Operating System-Specific Locations of Message Queue Data."

Creating an Audit Log

Message Queue supports audit logging in Enterprise Edition only. When audit logging is enabled, Message Queue generates a record for the following types of events:

To log audit records to the Message Queue broker log file, set the imq.audit.enabled broker property to true. All audit records in the log contain the keyword AUDIT.

For reference information about the imq.audit.enabled property, see Security Manager Properties.

Previous      Contents      Index      Next     

Part No: 819-0066-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.