Sun Java System Message Queue 3.5 SP1 Administration Guide |
Chapter 8
Managing SecurityThis 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. You can use a different user repository for each broker instance. The first part of this chapter explains how you create, populate, and manage that repository. For an introduction to Message Queue security, see "Security Manager".
Authorizing Users: the Access Control Properties File You are responsible for editing an access control properties file that maps each user’s access to broker operations to the user’s name or group membership. You can use a different access control properties file for each broker instance. The second part of this chapter explains how you can customize this file.
Encryption: Working With an SSL-based Service (Enterprise Edition) 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 Message Queue 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 an SSL keystore, an 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 UsersWhen 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 broker-specific user repository that each broker is configured to consult. This repository can be of two types:
- a flat-file repository that is shipped with Message Queue
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."
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, however it is secure and scalable, 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
Message Queue provides a flat-file user repository and a command line tool, Message Queue User Manager (imqusermgr) that you can use to populate and manage the flat-file user repository. The following sections describe the flat-file user repository and how you use the Message Queue User Manager utility (imqusermgr) to populate and manage that repository.
Creating a User Repository
The flat-file user repository is instance specific. A default user repository (named passwd) is created for each broker instance that you start. This user repository is placed in a directory identified by the name of the broker instance (instanceName) with which the repository is associated (see Appendix A, "Location of Message Queue Data"):
…/instances/instanceName/etc/passwd
The repository is created with two entries (rows), as illustrated in Table 8-1, 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 Message Queue 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 Message Queue broker to be used.
The initial guest user entry allows clients to connect to a broker instance using the default guest user name and password (for testing purposes, for example).
The initial admin user entry allows you to use imqcmd commands to administer a broker instance using the default admin user name and password. It is recommended that you update this initial entry to change the password (see "Changing the Default Administrator Password").
The following sections explain how you populate and manage a flat-file user repository.
User Manager Utility (imqusermgr)
The User Manager utility (imqusermgr) lets you edit or populate a flat-file user repository.
This section describes the basic imqusermgr command syntax, provides a listing of subcommands, and summarizes imqusermgr command options. Subsequent sections explain how you use the imqusermgr subcommands to accomplish specific tasks.
Before using imqusermgr, keep the following things in mind:
- If a broker-specific user repository does not yet exist, you have to 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 have to have the appropriate permissions to write to the repository,: namely, on Solaris and Linux, you have to be the root user or the user who first created the broker instance
Syntax of the imqusermgr Command
The general syntax of the imqusermgr command is as follows:
imqusermgr subcommand [options]
imqusermgr -h
imqusermgr -vNote 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.
Summary of imqusermgr Command Options
Table 8-3 lists the options to the imqusermgr command.
Groups
When adding a user entry to the user repository for a broker instance, you have 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.
- 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 will access the broker by being authenticated in the user group. By default, application client users in this group can produce messages to and consume messages from all topics and queues, or can browse messages in any queue by default.
- anonymous group. For Message Queue clients that do not wish to use 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 is analogous to the anonymous account present in most FTP servers. You 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 users from this group at deployment time.
In order 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 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 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:
- The user name 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 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 alladin:
imqusermgr update -u Katharine -p alladin
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
Changing the Default Administrator Password
For the sake of security, you should change the default password of admin to one that is only known to you. You need to use the imqusermgr tool to do this.
The following command changes the default password for the mybroker broker instance to grandpoobah.
imqusermgr update -i 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 should work.
imqcmd list svc -i mybroker -u admin -p grandpoobah
Using 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
If you want to use an LDAP server for a user repository, you must set certain broker properties in the instance configuration file. 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 certain messaging operations. The instance configuration file (config.properties) is located in a directory identified by the name of the broker instance (instanceName) with which the configuration file is associated (see Appendix A, "Location of Message Queue Data"):
…/instances/instanceName/props/config.properties
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 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
- 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. 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 imq.user.repos.ldap.server property in Table 8-5).
Table 8-5 LDAP-related Properties
Property
Description
imq.user_repository.
ldap.serverThe host:port for the LDAP server, where host specifies the fully qualified DNS name of the host running the directory server and port specifies the port number that the directory server is using for communications. To specify a list of failover servers, use the following syntax:
host1:port1 ldap://host2:port2 ldap://host3:port3…
where entries in the list are separated by spaces. Note that each failover server address after the first one begins with ldap.imq.user_repository.
ldap.principalThe 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.passwordThe password associated with the distinguished name used by the broker. This property can only be specified in a passfile (see "Using a Passfile").
There are a number of ways to provide a password. The most secure is to let the broker prompt you for a password. Less secure is to use a passfile and read-protect the passfile. Least secure is to 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.baseThe directory base for user entries.
imq.user_repository.
ldap.uidattrThe provider-specific attribute identifier whose value uniquely identifies a user. For example: uid, cn, etc.
imq.user_repository.
ldap.usrfilterA 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.grpsearchA 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 Message Queue.
Default: false
imq.user_repository.
ldap.grpbaseThe directory base for group entries.
imq.user_repository.
ldap.gidattrThe provider-specific attribute identifier whose value is a group name.
imq.user_repository.
ldap.memattrThe attribute identifier in a group entry whose values are the distinguished names of the group’s members.
imq.user_repository.
ldap.grpfiltlerA 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.timeoutAn integer specifying (in seconds) the time limit for a search. By default this is set to 180 seconds.
imq.user_repository.
ldap.ssl.enabledA 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.
- 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:
Authorizing Users:
the Access Control Properties FileAfter connecting to a broker instance, a user might 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 a broker-specific 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 ACL file to restrict these operations to certain users and groups.
The ACL file is used independently of whether user information is placed in a flat-file user repository (see "Using a Flat-File User Repository") or in an LDAP user repository (see "Using an LDAP Server for a User Repository").
Creating an Access Control Properties File
The ACL file is instance specific. A default file (named accesscontrol.properties) is created for each broker instance that you start. This ACL properties file is placed in a directory identified by the name of the broker instance (instanceName) with which the ACL file is associated (see Appendix A, "Location of Message Queue Data"):
…/instances/instanceName/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:
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.4/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 q1:
queue.q1.browse.allow.user=Bob
queue.q1.browse.deny.user=Bob
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:
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-based Service (Enterprise Edition)Message Queue 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 Message Queue 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 Message Queue’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-based Service Over TCP/IP
There are three SSL-based connection services that provide a direct, secure connection over TCP/IP.
ssljms This connection service is used to deliver 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 Message Queue Command utility (imqcmd)—the command line administration tool—and a broker. A secure connection is not supported for the Administration Console (imqadmin).
cluster This connection service is used to deliver messages over a secure, encrypted connection between brokers in a cluster (see "Secure Inter-Broker Connections").
To Set Up an SSL-based Connection Service
The procedures for setting up ssljms and ssladmin connection services are identical, except for Step 4, configuring and running the client.
Each of the steps is discussed in some detail in the sections that follow.
Step 1. Generating a Self-Signed Certificate
Message Queue’s SSL Support is oriented toward securing on-the-wire data with the assumption that the client is communicating with a known and trusted server. Therefore, 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 the ssljms connection service, ssladmin connection service, or cluster connection service. 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 places it in Message Queue’s keystore, located in a directory that depends upon the operating system, as shown in Appendix A, "Location of Message Queue Data."
The keystore is in the same format as that supported by the JDK1.2 keytool utility.
The configurable properties for the Message Queue 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.
dirpathFor SSL-based services: specifies the path to the directory containing the keystore file. Default: see Appendix A, "Location of Message Queue Data."
imq.keystore.file.name
For SSL-based services: specifies the name of the keystore file.
Default: keystoreimq.keystore.password
For SSL-based services: specifies the keystore password. This property can only be specified in a passfile (see "Using a Passfile").
There are a number of ways to provide a password. The most secure is to let the broker prompt you for a password. Less secure is to use a passfile and read-protect the passfile. Least secure is to specify the password using the following command line option: imqbrokerd -ldappassword.
You may need to regenerate a key pair in order to solve certain problems; for example:
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
- Remove the broker’s keystore, located as shown in Appendix A, "Location 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.
Note
The SSL-based cluster connection service is enabled using the imq.cluster.transport property rather than the imq.service.activelist property. See "Secure Inter-Broker Connections".
To Enable an SSL-based Service in the Broker
- 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, "Location 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 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
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 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 need to configure clients to use the secure connection services. There are two types of clients, depending on the connection service you are using: application clients that use ssljms, and the Message Queue administration clients (such as imqcmd) that use ssladmin. These are treated separately in the following sections.
Application Clients
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.
- 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 Java Client Developer’s Guide.
Administration Clients (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 Message Queue user repository. (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.
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 C, "HTTP/HTTPS Support (Enterprise Edition)".
Using a PassfileIn 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. This passfile can then be specified using the -passfile option when starting up a broker:
imqbrokerd -passfile myPassfile
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 set on the passfile need to provide read access to the user who starts the broker.
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 (see Table 8-8).
imq.user_repository.ldap.
passwordSpecifies the password associated with the distinguished name assigned to a broker for binding to a configured LDAP user repository (see Table 8-5).
imq.persist.jdbc.password
Specifies the password used to open a database connection, if required (see Table B-1).
A sample passfile can be found at a location that depends on operating system, as shown in Appendix A, "Location of Message Queue Data."