Chapter 7 Managing Security

As administrator, you configure 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.

Authenticating Users

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.

A flat-file repository that is shipped with Message Queue

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

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

Table 7-1 Initial Entries in User Repository
User Name	Password	Group	State
admin	admin	admin	active
guest	guest	anonymous	active

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.

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.



Note	Examples in the following sections assume the default broker instance.

Subcommands

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 imqusermgr Options
Option	Description
-a activeState	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.
-f	Performs action without user confirmation.
-h	Displays usage help. Nothing else on the command line is executed.
-i instanceName	Specifies the broker instance name 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.
-s	Sets silent mode.
-u userName	Specifies the user name.
-v	Displays version information. Nothing else on the command line is executed.

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

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

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.

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

Use the update subcommand to change a user’s password or state. For example, the following command changes Katharine’s password to 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

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.

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:

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

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:

To Edit the Configuration File to Use an LDAP Server

Specify that you are using an LDAP user repository by setting the following property:

imq.authentication.basic.user_repository=ldap

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

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.

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.

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

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.

Open the access control file, accesscontrol.properties. The location for the file is listed in Appendix A, "Platform-Specific Locations of Message Queue 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.

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

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

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

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

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.

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

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.

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:

Table 7-3 Syntactic Elements of Access Rules
Element	Description
resourceType	One of the following: connection, queue or topic.
resourceVariant	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.
operation	Value depends on the kind of access rule being formulated.
access	One of the following: allow or deny.
principalType	One of the following: user or group. For more information, see Groups.
principals	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.

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=*



Note	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

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:

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

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.

Table 7-4 Elements of Physical Destination Access Control Rules
Component	Description
resourceType	Can be queue or topic.
resourceVariant	A physical destination name or all physical destinations (*), meaning all queues or all topics.
operation	Can be produce, consume, or browse.
access	Can be allow or deny.
principalType	Can be user or group.

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:

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

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:

ssljms, ssladmin, and cluster are used over TCP/IP.

httpsjms is used over HTTP.

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:

The ssljms service delivers messages over a secure, encrypted connection between a client and broker.

The ssladmin service creates a secure, encrypted connection between the Message Queue Command utility (imqcmd) and a broker. A secure connection is not supported for the Administration Console (imqadmin).

The cluster service delivers messages and provides inter-broker communication over a secure, encrypted connection between brokers in a cluster (see Secure Connections Between Brokers).

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

Generate a self-signed certificate.

Enable the ssljms, ssladmin, or cluster connection service in the broker.

Start the broker.

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.

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 Key Tool utility to generate a self-signed certificate for the broker. On UNIX® systems you may need to run Key Tool 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.

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
Prompt	Description	Example
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.	myhost.sun.com
What is the name of your organizational unit?	The X.500 organizationalUnit (OU). Enter the name of a department or division.	purchasing
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.	California
What is the two-letter country code for this unit?	The X.500 country (C).	US

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

Is CN=mqserver.sun.com, 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, Key Tool pauses while it generates a key pair.

Next, Key Tool 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 key store password.


Note	Remember the password you provide. 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 Using a Password File).

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

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

imq.keystore.file.dirpath. For SSL-based services: specifies the path to the directory containing the key store file. For the default value, see Appendix A, "Platform-Specific Locations of Message Queue Data."

imq.keystore.file.name. For SSL-based services: specifies the name of the key store file.

imq.keystore.password. For SSL-based services: specifies the key store password.

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

You forgot the key store password.

The SSL-based service fails to initialize when you start a broker and you get the exception java.security.UnrecoverableKeyException: Cannot recover key.

To Regenerate a Key Pair

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

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.

To Enable an SSL-based Service in the Broker


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

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

…/instances/instanceName/props/config.properties

Add an entry (if one does not already exist) for the imq.service.activelist property and include SSL-based services in the list.

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

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

Step 3. Starting the Broker

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

Allow the broker to prompt you for the password when it starts up:

imqbrokerd
Please enter Keystore password: myPassword

Put the password in a password file, as described in Using a Password File. Once you have put the password in the password file and set the property imq.passfile.enabled=true, do one of the following:

Pass the location of the password file to the imqbrokerd command:

imqbrokerd -passfile /tmp/myPassfile

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=/tmp

imq.passfile.name=myPassfile

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 java.security.SecureRandom 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:

Application clients using ssljms

Message Queue administration clients (such as imqcmd) using ssladmin

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.

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:

jsse.jar, jnet.jar, jcert.jar, jndi.jar

Make sure the client has the following Message Queue .jar files in its class path:

imq.jar, jms.jar

Start the client and connect to the broker’s ssljms service. One way to do this is by entering a command like the following:

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:

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 key store, 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 http://java.sun.com.

Step 1: Obtaining and Installing a Signed Certificate

To Obtain a Signed Certificate

Use the J2SE keytool to generate a Certificate Signing Request (CSR) for the self-signed certificate you just generated.

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.

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.

When you get the signed certificate, save it in a file.

These instructions use the example name broker.cer to represent the broker certificate.

To Install a Signed Certificate

Check $JAVA_HOME/lib/security/cacerts to find out whether J2SE supports your CA by default, as follows:

keytool -v -list -keystore $JAVA_HOME/lib/security/cacerts

The command lists the root CAs in the system key store.

If your CA is listed, skip the next step.

If your CA is not supported in J2SE, import the certificate authority’s root certificate into the imqbrokerd key store.

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.

Import the signed certificate into the key store to replace the original self-signed certificate.

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 key store 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.

To configure the client to require a valid, signed certificate from imqbrokerd, set the imqSSLIsHostTrusted attribute to false for the client’s ConnectionFactory object.

Try to establish an SSL connection to imqbrokrd, as described under Step 4. Configuring and Running SSL-Based Clients.

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.

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

Install the root CA into the default system cacerts file.

Install the root CA into the alternative system file jssecacerts. This is the recommended option.

Install the root CA into any key store file and configure the client to use that as its trust store.

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 myStorePassword

The client searches this key store 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 key store by default, so no further client configuration is necessary.

Installing into Other Files

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

The client does not search this key store by default, so you must provide the location of the trust store to the client. To do so, set the Java system property javax.net.ssl.trustStore once the client is running. For example:

Using a Password File

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
Command	Purpose	Purpose of Password
imqbrokerd	Start the broker	Access a JDBC-based persistent data store, an SSL certificate key store, or an LDAP user repository
imqcmd	Manage the broker	Authenticate an administrative user who is authorized to use the command
imqdbmgr	Manage a JDBC-based data store	Access the data store

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:

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.


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

Table 7-7 Passwords in a Password File
Password	Affected Commands	Description
imq.imqcmd.password	imqcmd	Specifies the administrator password for an imqcmd command line. The password is authenticated for each command.
imq.keystore.password	imqbrokerd	Specifies the key store password for SSL-based services.
imq.persist.jdbc.password	imqbrokerd imdbmgr	Specifies the password used to open a database connection, if required.
imq.user_repository.ldap.password	imqbrokerd	Specifies the password associated with the distinguished name assigned to a broker for binding to a configured LDAP user repository.

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:

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.

Previous Contents Index Next
Sun Java System Message Queue 3 2005Q4 Administration Guide