Chapter 7 Managing Security

You manage security by configuring a user repository to authenticate users, to define access control, to configure a Secure Socket Layer (SSL) connection service that encrypts client-broker communication, and to set up a password file for use in broker startup.

The chapter includes the following sections:

• User Authentication

• User Authorization: The Access Control Properties File

• Message Encryption

• Password Files

• Audit Logging

User Authentication

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.

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.

The repository can be one of the following types:

• A flat-file repository that is shipped with Message Queue^TM

  This type of user repository is very easy to use. You can populate and manage the repository using the User Manager utility (imqusermgr). To enable authentication, you populate the user repository with each user’s name and password and the name of the user’s group.

  For more information on setting up and managing the user repository, see Using a Flat-File User Repository

• An LDAP server

  This could be an existing or new LDAP directory server that uses the LDAP v2 or v3 protocol. It is not as easy to use as the flat-file repository, but it is more scalable, and therefore better for production environments.

  If you are using an LDAP user repository, you use the tools provided by the LDAP vendor to populate and manage the user repository. For more information, see Using an LDAP Server for a User Repository.

Using a Flat-File User Repository

Message Queue provides a flat-file user repository and a command line tool, the User Manager utility (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 User Manager utility 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 automatically 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, Platform-Specific Locations of Message Queue^TM Data):

   …/instances/instanceName/etc/passwd

The repository is created with two entries. Each row of Table 7–1 shows an entry.

These initial entries allow the Message Queue broker to be used immediately after installation without intervention by the administrator:

• The initial guest user entry allows clients to connect to a broker instance using the default guest user name and password.

• 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

The Message Queue 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 Line Reference

Before using the User Manager, keep the following things in mind:

• If a broker-specific user repository does not yet exist, you must start up the corresponding broker instance to create it.

• The imqusermgr command has to be run on the host where the broker is installed.

• You must have appropriate permissions to write to the repository,: namely, on Solaris and Linux, you must be the root user or the user who first created the broker instance.

Examples in the following sections assume the default broker instance.

Subcommands

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

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

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

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

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

Groups

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. Groups should be assigned as follows:

• admin group. For broker administrators. Users who are assigned this group can, by default, configure, administer, and manage the broker. You can assign more than one user to the admin group.

• user group. For normal (non-administration) Message Queue client users. Most client users are in the user group. By default, users in this group can produce messages to all topics and queues, consume messages from all topics and queues, and browse messages in any queue.

• anonymous group. For Message Queue clients that do not want a user name that is known to the broker, possibly because the client application does not know of a real user name to use. This account is analogous to the anonymous account present in most FTP servers. You can assign only one user at a time to the anonymous group. You should restrict the access privileges of this group as compared to the user group or you should remove users from the group at deployment time.

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 User Authorization: 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:

• A user name cannot contain an asterisk (*), comma (,), colon (:), or a new-line or carriage-return character.

• A user name or password must be at least one character long.

• If a user name or password contains a space, the entire name or password must be enclosed in quotation marks.

• There is no limit on the length of passwords or user names, except for command shell restrictions on the maximum number of characters that can be entered on a command line.

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 known only to you. 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

• Setting up access control for administrators

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, config.properties. These properties enable the broker instance to query the LDAP server for information about users and groups whenever a user attempts to connect to the broker instance or perform messaging operations.

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

…/instances/instanceName

/props/config.properties

For information about the operating system-specific location of instance directories, see Appendix A, Platform-Specific Locations of Message Queue^TM 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:

   imq.authentication.basic.user_repository=ldap

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

   imq.authentication.type=basic

3. 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 discussed under Security Services and summarized under Security Properties.

   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 config.properties file for a sample of how to set properties related to LDAP user-repository.

4. 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 User Authorization: The Access Control Properties File.

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

     When employing multiple LDAP directory servers, use ldap:// to specify each additional directory server. For example:

     imq.user_repository.ldap.server= myHost:7878 ldap:// otherHost:7878 …

     Separate each additional directory server with a space. All directory servers in the list must use the same values for other LDAP-related 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.

   The imq.accesscontrol.enabled property enables use of the access control file.

2. Open the access control file, accesscontrol.properties. The location for the file is listed in Appendix A, Platform-Specific Locations of Message Queue^TM Data

   The file contains an entry such as the following:

   service connection access control##################################connection.NORMAL.allow.user=*connection.ADMIN.allow.group=admin

   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.

3. To grant Message Queue administrator privileges to users, enter the user names as follows:

   connection.ADMIN.allow.user= userName[[,userName2] …]

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

   connection.ADMIN.allow.group= groupName[[,groupName2] …]

User Authorization: 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.

The ACL file is used whether user information is placed in a flat-file user repository or in an LDAP user repository. A broker checks its ACL file when a client application performs one of the following operations:

• Creates a connection

• Creates a producer

• Creates a consumer

• Browses a queue

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 the broker checks the file to verify authorization. You need not restart the broker after editing the file.

Creating an Access Control Properties File

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

…/instances/brokerInstanceName/etc/accesscontrol.properties

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:

• Connection access control

• Physical destination access control

• Physical destination auto-create access control

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

version=JMQFileAccessControlModel/100

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.

Here are some examples of access rules:

• The following rule means that all users may send a message to the queue named q1.

  queue.q1.produce.allow.user=*

• The following rule means that any user may send messages to any queue.

  queue.*.produce.allow.user=*

To specify non-ASCII user, group, or destination names, use Unicode escape (\\uXXXX) notation. If you have edited and saved the ACL file with these names in a non-ASCII encoding, you can convert the file to ASCII with the Java native2ascii tool. For more detailed information, see

http://java.sun.com/j2se/1.4/docs/guide/intl/faq.html

How Permissions are Computed

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

• Specific access rules override general access rules. After applying the following two rules, all users can send to all queues, but Bob cannot send to tq1.

  queue.*.produce.allow.user=*
  queue.tq1.produce.deny.user=Bob

• Access given to an explicit principal overrides access given to a * principal. The following rules deny Bob the right to produce messages to tq1, but allow everyone else to do it.

  queue.tq1.produce.allow.user=*
  queue.tq1.produce.deny.user=Bob

• The * principal rule for users overrides the corresponding * principal for groups. For example, the following two rules allow all authenticated users to send messages to tq1.

  queue.tq1.produce.allow.user=*
  queue.tq1.produce.deny.group=*

• Access granted a user overrides access granted to the user’s group. In the following example, even if Bob is a member of User, he cannot produce messages to tq1. All other members of User will be able to do so.

  queue.tq1.produce.allow.group=User
  queue.tq1.produce.deny.user=Bob

• Any access permission not explicitly granted through an access rule is implicitly denied. For example, if the ACL file contains no access rules, all users are denied all operations.

• Deny and allow permissions for the same user or group cancel themselves out. For example, the following two rules cause Bob to be unable to browse q1:

  queue.q1.browse.allow.user=Bob
  queue.q1.browse.deny.user=Bob

  The following two rules prevent the group User from consuming messages at q5.

  queue.q5.consume.allow.group=User
  queue.q5.consume.deny.group=User

• When multiple same left-hand rules exist, only the last entry takes effect.

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:

connection.NORMAL.allow.user=*
connection.ADMIN.allow.group=admin

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

• Define a group called admin in the LDAP directory.

• Replace the name admin in the ACL properties file with the names of one or more groups that are defined in the LDAP directory.

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

connection.NORMAL.deny.user=Bob
connection.NORMAL.allow.user=*

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:

• File-based user repository

  • If access control is disabled, users in the group admin have ADMIN connection privileges.

  • If access control is enabled, edit the ACL file. Explicitly grant users or groups access to the ADMIN connection service.

• LDAP user repository. If you are using an LDAP user repository, do all of the following:

  • Enable access control.

  • Edit the ACL file and provide the names of users or groups who can make ADMIN connections. Specify any users or groups that are defined in the LDAP directory server.

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

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:

• Allow all users to send messages to any queue destinations.

  queue.*.produce.allow.user=*

• Deny any member of the group user the ability to subscribe to the topic Admissions.

  topic.Admissions.consume.deny.group=user

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:

queue.create.allow.user=*
topic.create.allow.user=*

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.

topic.create.allow.user=*
topic.create.deny.user=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.

Message Encryption

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.

Using Self-Signed Certificates

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.

To Set Up an SSL-Based Connection Service Using Self-Signed Certificates

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.

   This step applies only to the ssljms connection service and not to ssladmin or cluster.

Generating a Self-Signed Certificate

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.

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 Queue^TM 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 Queue^TM Data.

• imq.keystore.file.name: The name of the key store file.

• imq.keystore.password: The key store password.

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

To Regenerate a Key Pair

1. Remove the broker’s key store, located as shown in Appendix A, Platform-Specific Locations of Message Queue^TM Data.

2. Run imqkeytool again to generate a new key pair, as described above.

Enabling an SSL-Based Connection Service

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

To Enable an SSL-Based Service in the Broker

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^TM Data):

   .../instances/instanceName/props/config.properties
   

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

   imq.service.activelist=jms,admin,ssljms,ssladmin
   

   ---

   Note –

   The SSL-based cluster connection service is enabled using the imq.cluster.transport property rather than the imq.service.activelist property; see Connecting Brokers.

   ---

3. Save and close the instance configuration file.

Starting the Broker

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.

Configuring and Running an SSL-Based Client

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

Application Clients

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.

Administrative Clients

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.

Using Signed Certificates

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.

To Use a Signed Certificate

1. Install the certificate in the key store.

2. Configure the Message Queue client to require signed certificates when establishing an SSL-based connection to the broker.

Obtaining and Installing a Signed Certificate

The following procedures explain how to obtain and install a signed certificate.

To Obtain a Signed Certificate

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

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

3. Save the signed certificate in a file.

   The instructions below use the example name broker.cer to represent the broker certificate.

To Install a Signed Certificate

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

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

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

Configuring the Message Queue Client Runtime to Require Signed Certificates

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.

To Configure the Client Runtime to Require Signed Certificates

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

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

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

Password Files

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.

You can specify these passwords in a password file 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 the current 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 password file on the command line. For non-interactive use of commands, however, you must use a password file.

A password file 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.

Password File Contents

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

A password file can contain the passwords shown in Table 7–7:

imq.keystore.password

imq.persist.jdbc.password

imqbrokerd
imdbmgr

imq.user_repository.ldap.password

imqbrokerd

A sample password file is part of the Message Queue product. For the location of the sample file, see Appendix A, Platform-Specific Locations of Message Queue^TM Data

Connecting Through a Firewall

When a client application is separated from the broker by a firewall, special measures are needed in order to establish a connection. One approach is to use the httpjms or httpsjms connection service, which can “tunnel” through the firewall; see Appendix C, HTTP/HTTPS Support for details. HTTP connections are slower than other connection services, however; a faster alternative is to bypass the Message Queue Port Mapper and explicitly assign a static port address to the desired connection service, and then open that specific port in the firewall. This approach can be used to connect through a firewall using the jms or ssljms connection service (or, in unusual cases, admin or ssladmin).

To Enable Broker Connections Through a Firewall

1. Assign a static port address to the connection service you wish to use.

   To bypass the Port Mapper and assign a static port number directly to a connection service, set the broker configuration property imq.serviceName.protocolType.port, where serviceName is the name of the connection service and protocolType is its protocol type (see Table 7–8). As with all broker configuration properties, you can specify this property either in the broker's instance configuration file or from the command line when starting the broker. For example, to assign port number 10234 to the jms connection service, either include the line

      imq.jms.tcp.port=10234
   

   in the configuration file or start the broker with the command

      
   imqbrokerd  -name myBroker  -Dimq.jms.tcp.port=10234
   

2. Configure the firewall to allow connections to the port number you assigned to the connection service.

   You must also allow connections through the firewall to Message Queue's Port Mapper port (normally 7676, unless you have reassigned the Port Mapper to some other port). In the example above, for instance, you would need to open the firewall for ports 10234 and 7676.

Audit Logging

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:

• Startup, shutdown, restart, and removal of a broker instance

• User authentication and authorization

• Reset of a persistent store

• Creation, purge, and destruction of a physical destination

• Administrative destruction of a durable subscriber

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.