Chapter 8   Security Management

This chapter explains how to perform tasks related to security, these include authentication, authorization, and encryption.

Authenticating Users    You are responsible for maintaining a list of users, their groups, and passwords in a user repository. The first part of this chapter explains how you create, populate, and manage that repository. For an introduction to Sun™ ONE Message Queue (MQ) security, see "Security Manager".

Authorizing Users    You are responsible for editing a properties file that maps the user's access to broker operations to the user's name or group. The second part of this chapter explains how you can customize this properties file.

Encryption: Setting Up SSL Services    Using a connection service based on the Secure Socket Layer (SSL) standard allows you to encrypt messages sent between clients and broker. For an introduction to how MQ handles encryption, see "Encryption (Enterprise Edition)". The last part of this chapter explains how to set up an SSL-based connection service and provides additional information about using SSL.

For situations in which a password is needed for a broker to secure access to a SSL keystore, a LDAP user repository, or a JDBC-compliant persistent store, there are three means of providing such passwords:

• by having the system prompt you when the broker is started
• by passing in passwords as command line options when starting the broker (see "Starting a Broker" and Table 5-2)
• by storing passwords in a passfile that the system accesses when starting the broker (See "Using a Passfile")

Authenticating Users

---

When a user attempts to connect to the broker, the broker authenticates the user by inspecting the name and password provided, and grants the connection if they match those in a user repository that the broker is configured to consult. This repository can be of two types:

• a flat-file repository that is shipped with MQ

This type of user repository is very easy to use; however it is vulnerable to security attacks, and should therefore be used only for evaluation and development purposes. 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, 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 for your user repository. It is not as easy to use as the flat-file repository, however it is secure, and therefore better for production environments.

If you are using an LDAP user repository, you will need to 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

MQ provides a flat-file user repository and a command line tool, MQ 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, its initial entries, and how you populate and manage that repository.

The default flat-file repository is located at:

IMQ_HOME/etc/passwd (/etc/imq/passwd on Solaris)

The repository is shipped with two entries (rows) already defined, as illustrated in the table below.

Table 8-1    Initial Entries in User Repository 

User Name	Password	Group	State
admin	admin	admin	active
guest	guest	anonymous	active

These initial entries allow the MQ broker to be used immediately after installation without any intervention by the administrator. In other words, no initial user/password setup is required for the MQ broker to be used.

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

The initial admin user entry allows you to use imqcmd commands to administer the broker using the default admin user name and password. It is recommended that you update this initial entry to change the password.

You can use the User Manager utility to edit or populate the flat-file user repository without having to first configure or start up the broker. The only requirement for using the User Manager utility is that it be run on the host where the broker is installed, and that if you want to write to the repository, you have to have the appropriate permissions:

• On Solaris, the User Manager utility can be run by the root user, or by other non-root users granted access through Solaris role based access control. To grant such access, the root user must make an entry to /etc/user_attr of the following form:

username::::type=normal;profiles=Message Queue Management

This adds the specified user to the MQ rights profile. To use this facility, you first must run a profile shell (pfsh, pfksh, pfcsh), for example,

% /usr/bin/pfsh

and then execute the desired User Manager (imqusermgr) commands.

For more information on Solaris role based access control, see: http://docs.sun.com/
?q=Rights+Profile&p=/doc/806-4078/6jd6cjrvl&a=view).

• On Windows, after installation, the user repository file can be written to by any user because the operating system does not control access to files using user name-based permission attributes.

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

User Manager Utility (imqusermgr)

The User Manager utility allows you to manage a file-based user repository. This section describes the basic imqusermgr command syntax, provides a listing of subcommands, and summarizes imqusermgr command options. Subsequent sections explain how you use the imqobjmgr subcommands to accomplish specific tasks.

Syntax of Command

The general syntax of the imqusermgr command is as follows:

imqusermgr subcommand [options]
imqusermgr -h
imqusermgr -v

Note that if you specify the -v or -h options, no subcommands specified on the command line are executed. For example, if you enter the following command, version information is displayed but the list subcommand is not executed.

imqusermgr list -v

imqusermgr Subcommands

Table 8-2 lists the imqusermgr subcommands.

Table 8-2    imqusermgr Subcommands 

Subcommand	Description
add -u name -p passwd [-g group] [-s]	Adds a user and associated password to the repository, and optionally specifies the user's group.
delete -u name [-s] [-f]	Deletes the specified user from the repository.
list [-u name]	Displays information about the specified user or all users.
update -u name -p passwd [-a state] [-s] [-f] update -u name -a state [-p passwd] [-s] [-f]	Updates the specified user's password and/or state.

Summary of imqusermgr Command Options

Table 8-3 lists the options to the imqusermgr command.

Table 8-3    imqusermgr Options  

Option	Description
-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.
-f	Performs action without user confirmation
-h	Displays usage help. Nothing else on the command line is executed.
-p passwd	Specifies the user's password.
-g group	Specifies the user group. Valid values are admin, user, anonymous.
-s	Sets silent mode.
-u name	Specifies the user name.
-v	Displays version information. Nothing else on the command line is executed.

Groups

When adding a user entry to the repository, the administrator has the option of specifying one of three predefined groups for the user: admin, user, or anonymous. If no group is specified, the default group user is assigned.

• The admin group is for broker administrators. Users who are assigned this group can, by default, configure, administer, and manage the broker. The administrator can assign more than one user to the admin group.
• The user group is for normal (non-administrative) JMS client applications. Most MQ client applications will access the broker authenticated in the user group. As such, client applications, can produce messages to and consume messages from all topics and queues, or can browse messages in any queue by default.
• The anonymous group is for JMS client applications who do not wish to use a user name that is known to the broker (possibly because the application does not know of a real user name to use). This is analogous to the anonymous account present in most FTP servers. The administrator can assign only one user to the anonymous group at any one time. It is expected that you will restrict the access privileges of this group as compared to the user group through access control or that you will remove the user from this group at deployment time.

In order to change a user's group, the administrator must delete the user entry and then add another entry for the user, specifying the new group.

You can specify access rules that define what operations the members of that group may perform. For more information, see "Authorizing Users: the Access Control Properties File".

States

When the administrator adds a user to the repository, the user's state is active by default. To make the user inactive, the administrator 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 the administrator adds another user who has the same name, the operation will fail. The administrator must delete the inactive user entry or change the new user's name or use a different name for the new user. This prevents the administrator from adding duplicate names or passwords.

Format of User Names and Passwords

User names and passwords must follow these guidelines:

• The user name and passwords may not contain the characters listed in Table 8-4.

Table 8-4    Invalid Characters for User Names and Passwords 

Character	Description
*	Asterisk
,	Comma
:	Colon

• The user name and passwords may not contain a new line or carriage return as characters.
• If the name or password contains a space, the entire name or password must be enclosed in quotation marks.
• The name or password must be at least one character long.
• There is no limit on the length of passwords or user names—except for that imposed by the command shell on the maximum number of characters that can be entered on a command line.

Populating and Managing the User Repository

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

imqusermgr add -u Katharine -p sesame -g user

Use the delete subcommand to delete a user from the 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 alladin:

imqusermgr update -u Katharine -p alladin

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

imqusermgr list -u isa

---

---------------------------------- User Name    Group     Active State ---------------------------------- isa          admin    true

---

The following command lists information about all users:

imqusermgr list

---

-------------------------------------- User Name    Group        Active State -------------------------------------- testuser3    user         true testuser2    user         true testuser1    user         true isa          admin        true admin        admin        true guest        anonymous    true testuser5    user         false testuser4    user         false

---

Changing the Default Administrator Password

For the sake of security, you must 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 password to grandpoobah.

imqusermgr update -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 is running. For example, the following command should work,

imqcmd list svc -u admin -p grandpoobah

While using the old password should fail.

After changing the password, you should supply the new password when using any of the administration tools, including the administration console.

Using an LDAP Server for a User Repository

If you want to use an LDAP server for your user repository, you must set certain broker properties in the instance configuration file. These properties enable the broker to query the LDAP server for information about users and groups when a user attempts to connect to the broker or perform certain operations. The instance configuration file is located at

IMQ_VARHOME/instances/brokerName/props/config.properties
(/var/imq/instances/brokerName/props/config.properties on Solaris)

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

imq.authentication.type=basic

3. You must also set the broker properties that control LDAP access. These properties, stored in a broker's instance configuration file, are described in Table 8-5. MQ uses JNDI API's to communicate with the LDAP directory server. Consult JNDI documentation for more information on syntax and on terms referenced in these properties. MQ 3.0.1 uses a Sun JNDI LDAP provider and uses simple authentication.

Table 8-5    LDAP-related Properties 

Property	Description
imq.user_repository. ldap.server	The host:port for the LDAP server. Host specifies the fully qualified DNS name of the host running the directory server. Port specifies the port number that the directory server is using for communications.
imq.user_repository. ldap.principal	The distinguished name that the broker will use to bind to the directory server for a search. If the directory server allows anonymous searches, this property does not need to be assigned a value.
imq.user_repository. ldap.password	The password associated with the distinguished name used by the broker. Can only be specified in a passfile (see "Using a Passfile"). For more security, let the broker prompt you for a password, or specify the password using the following command line option: imqbrokerd -ldappassword. If the directory server allows anonymous searches, no password is needed.
imq.user_repository. ldap.base	The directory base for user entries.
imq.user_repository. ldap.uidattr	The provider-specific attribute identifier whose value uniquely identifies a user. For example: uid, cn, etc.
imq.user_repository. ldap.usrfilter	A JNDI search filter (a search query expressed as a logical expression). By specifying a search filter for users, the broker can narrow the scope of a search and thus make it more efficient. For more information, see the JNDI tutorial at the following location: http://java.sun.com/products/jndi/tutorial. This property does not have to be set.
imq.user_repository. ldap.grpsearch	A boolean specifying whether you want to enable group searches. Consult the documentation provided by your LDAP provider to determine whether you can associate users into groups. Note that nested groups are not supported in MQ 3.0.1. Default: false
imq.user_repository. ldap.grpbase	The directory base for group entries.
imq.user_repository. ldap.gidattr	The provider-specific attribute identifier whose value is a group name.
imq.user_repository. ldap.memattr	The attribute identifier in a group entry whose values are the distinguished names of the group's members.
imq.user_repository. ldap.grpfiltler	A JNDI search filter (a search query expressed as a logical expression). By specifying a search filter for groups, the broker can narrow the scope of a search and thus make it more efficient. For more information, see the JNDI tutorial at the following location. http://java.sun.com/products/ jndi/tutorial This property does not have to be set.
imq.user_repository. ldap.timeout	An integer specifying (in seconds) the time limit for a search. By default this is set to 180 seconds.
imq.user_repository. ldap.ssl.enabled	A boolean specifying whether the broker should use the SSL protocol when talking to an LDAP server. This is set to false by default.

See the broker's default.properties file for a sample (default) LDAP user- repository-related properties setup.

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 "Authorizing Users: 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 a secure port for the LDAP user repository property. For example:

   imq.user_repository.ldap.server=myhost:7878

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

Authorizing Users:
the Access Control Properties File

---

After connecting to the broker, the user may want to produce a message, consume a message at a destination, or browse messages at a queue destination. When the user attempts to do this, the broker checks an access control properties file (ACL file) to see whether the user is authorized to perform the operation. The ACL file contains rules that specify which operations a particular user (or group of users) is authorized to perform. By default, all authenticated users are allowed to produce and consume messages at any destination. You can edit the access control properties file to restrict these operations to certain users and groups.

The ACL file is used whether user information is placed in a flat-file repository or in an LDAP repository. A default ACL properties file is installed along with the broker. Its name is accesscontrol.properties and it is placed by the installer in the following directory:

IMQ_HOME/etc (/etc/imq on Solaris)

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
• destination access control
• 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.

Access Rules Syntax

In the ACL properties file, access control defines what access specific users or groups have to protected resources like 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 8-6 describes the elements of syntax rules.

Table 8-6    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 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.

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

---

Note

To specify non-ASCII user, group, or destination names, you must 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.3/docs/guide/intl/faq.html

---

Permission Computation

The following principles are applied when computing the permissions implied by a series of rules:

• Specific access rules override general access rules. After applying the following two rules, all 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, if Bob is a member of User, he will be denied permission to produce messages to tq1, but 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 contained no access rules, all users would be denied all operations.
• Deny and allow permissions for the same user or group cancel themselves out. For example, the following two rules result in Bob not being able to browse t1:

queue.q1.browse.allow.user=Bob

queue.q1.browse.deny.user=Bob

The following two rules result in the group User not being able to consume 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.

Connection Access Control

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. By default all users can have access to the NORMAL type, but only those users whose group is admin may have access to ADMIN type connection services.

You can edit the connection access control rules to restrict a user's 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.

You may not create your own service type; you must restrict yourself to the predefined types specified by the constants NORMAL and ADMIN.

Destination Access Control

The destination access control section of the access control properties file contains destination-based access control rules. These rules determine who (users/groups) may do what (operations) where (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 destination. You can add more specific destination access rules or edit the default rules. The rest of this section explains the syntax of 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 8-7 describes these elements:

Table 8-7    Elements of Destination Access Control Rules

Component	Description
resourceType	Must be one of queue or topic.
resourceVariant	A destination name or all destinations (*), meaning all queues or all topics.
operation	Must be one of produce, consume, or browse.
access	Must be one of allow or deny.
principalType	Must be one of 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 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 to subscribe to the topic Admissions.

topic.Admissions.consume.deny.group=user

Destination Auto-Create Access Control

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

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

By default, any user or group has the privilege of having a 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 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 destination auto-create rules must be congruent with that of 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 destination if it does not exist but it will not deliver a message to it.

Encryption: Working With an SSL Service (Enterprise Edition)

---

The MQ Enterprise Edition supports connection services based on the Secure Socket Layer (SSL) standard: over TCP/IP (ssljms and ssladmin) and over HTTP (httpsjms). These SSL-based connection services allow for the encryption of messages sent between clients and broker. The current MQ release supports SSL encryption based on self-signed server certificates.

To use an SSL-based connection service, you need to 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 MQ's SSL-based connection services are similar in concept, there are some differences in how you set them up. Secure connections over TCP/IP and over HTTP are therefore discussed separately in the following sections.

Setting Up an SSL Service Over TCP/IP

There are two SSL-based connection services that provide a direct, secure connection over TCP/IP.

ssljms    This connection service is used to deliver JMS messages over a secure, encrypted connection between a client and broker.

ssladmin   

This connection service is used to create a secure, encrypted connection between the Command utility (imqcmd)—the command line administration tool—and a broker. A secure connection is not supported for the Administration Console (imqadmin).

To set up a ssljms connection service

1. Generate a self-signed certificate.
2. Enable the ssljms connection service in the broker.
3. Start the broker.
4. Configure and run the client.

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

SSL Support in MQ 3.0.1 is oriented toward securing on-the-wire data with the assumption that the client is communicating with a known and trusted server. Therefore in MQ 3.0.1, SSL is implemented using only self-signed certificates.

Run the imqkeytool command to generate a self-signed certificate for the broker. The same certificate can be used for both the ssljms and ssladmin connection services. Enter the following at the command prompt:

imqkeytool -broker

The utility will prompt you for the information it needs. (On Unix systems you may need to run imqkeytool as the superuser (root) in order to have permission to create the keystore.)

First, imqkeytool prompts you for a keystore password, then it prompts you for some organizational information, and then it prompts you for confirmation. After it receives the confirmation, it pauses while it generates a key pair. It then asks you for a password to lock the particular key pair (key password); you should enter Return in response to this prompt: this makes the key password the same as the keystore password.

---

Note	Remember the password you provide—you will need to provide this password later to the broker (when you start it) so it can open the keystore. You can also 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 to place it in MQ's keystore, located at

IMQ_HOME/etc/keystore (/etc/imq/keystore on Solaris)

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

The configurable properties for the MQ keystore are shown in Table 8-8. (For instructions on configuring these properties, see Chapter 5, "Starting and Configuring a Broker.")

Table 8-8    Keystore Properties 

Property Name	Description
imq.keystore.file. dirpath	For SSL-based services: specifies the path to the directory containing the keystore file. Default: IMQ_HOME/etc (/etc/imq/ on Solaris)
imq.keystore.file.name	For SSL-based services: specifies the name of the keystore file. Default: keystore
imq.keystore.password	For SSL-based services: specifies the keystore password. Can only be stored in a passfile (see "Using a Passfile"). For more security, let the broker prompt you for the password, or specify the password using the following command line option: imqbrokerd -password.

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

• You forgot the keystore password.
• The SSL service fails to initialize when you start a broker and you get the exception:
  java.security.UnrecoverableKeyException: Cannot recover key.

This exception may result from the fact that you had provided a key password that was different from the keystore password when you generated the self-signed certificate in "Step 1. Generating a Self-Signed Certificate".

To regenerate a key pair

1. Remove the broker's keystore, at the following location:

IMQ_HOME/etc/keystore (/etc/imq/keystore on Solaris)

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 service in the broker, you need to add ssljms (ssladmin) to the imq.service.activelist property.

1. Open the broker's instance configuration file. You can find it at the following location:

IMQ_VARHOME/instances/brokerName/props/config.properties
(/var/imq/instances/brokerName/props/config.properties on Solaris)

where brokerName is the name of the broker instance.

2. Add the ssljms or ssladmin values or both (depending on the service you want) to the imq.service.activelist property:

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

Step 3. Starting the Broker

Start the broker, providing the keystore 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

• Use the -password option to the imqbrokerd command:

imqbrokerd -password mypassword

• Put the password in a passfile file (see "Using a Passfile") which is accessed at broker startup. You have to first set the following broker configuration property (see "Editing the Instance Configuration File"):

imq.passfile.enabled=true

Once this property is set, you can access the passfile in either of two ways:

• pass the location of the passfile to the imqbrokerd command:

imqbrokerd -passfile /tmp/mypassfile

• start the broker without the -passfile option, but specify the location of the passfile using the following two broker configuration properties:

imq.passfile.dirpath=/tmp

imq.passfile.name=mypassfile

For a listing of passfile-related broker properties, see Table 2-6.

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 MQ 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 need to configure clients to use the secure connection services. There are two types of clients, depending on the connection service you are using: JMS clients that use ssljms, and the MQ administration Command utility (imqcmd) that uses ssladmin. These are treated separately in the following sections.

JMS Client

You have to 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:

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

2. Make sure the client has the following MQ jar files in its class path:

imq.jar, jms.jar

3. 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 MQ Developer's Guide.

Command Utility (imqcmd)

You can establish a secure administration connection by including the -secure option when using imqcmd (see Table 6-2) for example:

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

where adminName and adminPassword are valid entries in the MQ user repository (if using a flat file repository, see "Changing the Default Administrator Password").

Listing the connection services, as in this example, 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.

---

Setting Up an SSL Service Over HTTP

In this SSL-based connection service (httpsjms), the client and broker establish a secure connection by way of a HTTPS tunnel servlet. The architecture and implementation of HTTPS support is described in Appendix B "HTTP/HTTPS Support (Enterprise Edition)" on page 213.

Using a Passfile

---

In cases where you want the broker to start up without prompting you for needed passwords, or without requiring you to supply these passwords as options to the imqbrokerd command, you can place the needed passwords in a passfile.

A passfile is a simple text file containing passwords. The file is not encrypted, and therefore less secure than supplying passwords manually. Nevertheless you can set permissions on the file that limit who has access to view it. The permissions on the passfile need to give the user who starts the broker permission to read it.

A passfile can contain the passwords shown in Table 8-9:

Table 8-9    Passwords in a Passfile

Password	Description
imq.keystore.password	Specifies the keystore password for SSL-based services.
imq.user_repository.ldap. password	Specifies the password associated with the distinguished name assigned to a broker for binding to a configured LDAP user repository.
imq.persist.jdbc.password	Specifies the password used to open a database connection, if required.

A sample passfile can be found at the following location:

IMQ_HOME/etc/passfile.sample (/etc/imq/passfile.sample on Solaris)