Usage guide

To use queue base security, the queue manager that owns the queue must have a private registry. If the MQeWTLSCertAuthenticator is used, the registry must also have its own credentials, which it obtains by auto-registering with the mini-certificate server. In the following example the credentials process is enabled by adding information to the Registry Section of the queue manager's configuration (.ini) file. If the MQeWTLSCertAuthenticator is not used, a private registry is still required but it does not have to register with the mini-certificate server to obtain credentials.

The following code fragments provide an example of how to create queue manager instances and define the queues identified for the queue-based scenario described in Usage scenario.

Using qm_create to create ClientQMgr and ServerQMgr instances

Note:
This example program takes the private registry PIN, the PIN, the Certificate-request PIN, and the Key Ring Password from your command line if required. This is convenient for an example but is not recommended for a production system. Care should be taken to prevent the unauthorized disclosure of PINs and passwords.

qm_create assists users to create queue manager instances that have private registries. The class uses parameters found in the Registry Section of MQePrivateClient1.ini and MQePrivateServer1.ini.

The particular instances can be created as follows:

  1. If auto-registration with an MiniCertificateServer is required, an WebSphere MQ Everyplace Java MiniCertificateServerGUI must be started, using 'administration' mode, to define the queue manager instances (ClientQMgr and ServerQMgr) as valid authenticatable entities with their certificate request PIN set to the same value as that provided on your command line.
  2. Use qm_create to create queue managers ClientQMgr and ServerQMgr. The PIN, the Certificate-request PIN and the Key Ring Password parameters must also be specified if MQeWTLSCertAuthenticator is to be used. For example:
    qm_create ServerQMgr -p 12345678 -c 12345678 -k It_is_a_secret -s 127.0.0.1:8082
     
    qm_create ClientQMgr -p 12345678 -c 22345678 -k It_is_a_secret -s 127.0.0.1:8082
    
  3. Start a MiniCertificateServerGUI instance and select 'server' mode.
  4. Run the TestCreate program (shown in the following code fragment) to create the queue manager instances.

Defining the queues identified for the queue-based scenario described above

There are several ways to add queue definitions to a queue manager instance. The method described here starts the queue manager instance locally, adds the new queue definitions by creating the relevant administration messages and sending them to the queue manager's own administration queue, and then waits for confirmation of success in an AdminReply queue.

ClientQMgr queues -adding TestClient_HomeServerQ

Start the ClientQMgr locally then create and use administration messages to add the queue and set the poll interval.

q_create ClientQMgr TestClient_HomeServerQ -h ServerQMgr Network:127.0.0.1:8081 
TestServer_StoreAndForwardQ -p 12345678 -c 12345678 -k It_is_a_secret 
                            -s FastNetwork:127.0.0.1:8082

ClientQMgr queues -adding XXX_service_reply queue

Start the ClientQMgr locally then create and use an administration messages to add the queue.

q_create ClientQMgr XXX_service_reply -r -p 12345678 -c 12345678 
-k It_is_a_secret -s FastNetwork:127.0.0.1:8082

ServerQMgr queues -adding TestServer_StoreAndForwardQ

Start the ServerQMgr locally , create and use an administration messages to add the queue, and then add a remote queue manager reference.

q_create ServerQMgr TestServer_StoreAndForwardQ -f ClientQMgr -p 12345678 
-c 12345678 -k It_is_a_secret -s FastNetwork:127.0.0.1:8082

ServerQMgr queues -adding XXX_service_request queue

Start the ServerQMgr locally using the MQePrivateClient class, (using a different version, MQePrivateServer2.ini, that deliberately does not hold hard coded values for PIN, KeyRingPassword and CertReqPIN) then create and use an administration messages to add the queue.

q_create ServerQMgr XXX_service_request -q -p 12345678 -c 12345678 
-k It_is_a_secret -s FastNetwork:127.0.0.1:8082

Example Server TestService application

An example Server TestService program, securityTestService, is provided. It can be started by the command:

securityTestService ServerQMgr ClientQMgr -p 12345678 -c 12345678 
-k It_is_a_secret -s FastNetwork:127.0.0.1:8082

Client queue manager application initiating XXX_service_request.

The example queue-based security scenario in Usage scenario describes a client queue manager application that initiates XXX_service_request messages by encapsulating the request in a MQeMsgObject and using putMessage() to reliably deliver the request to the server queue manager's XXX_sevice_request queue. It then waits for the reply to the service request by using waitForReply() on its own XXX_service_reply queue.

In the scenario, the TestService application on the server processes the service request by using getMessage() to get the service request from the XXX_service_request queue, processes the request (for example by invocation of a backend transaction), builds the reply MQeMsgObject, and uses the server queue manager putMessage() to return the reply to the (remote) initiating client queue manager.

The server queue manager internally puts the message onto its TestServer_StoreAndForwardQ. The client queue manager pulls the message from the TestServer_StoreAndForwardQ and receives it in its ClientTest_HomeServerQ before putting it on the intended target XXX_service_reply queue.

An example Client TestService program, securityTestClient, is also provided. It invokes a service request and processes the resulting reply. This example can be started by the command:

securityTestClient ClientQMgr ServerQMgr Network:127.0.0.1:8081 -p 12345678 
-c 22345678 -k It_is_a_secret -s FastNetwork:127.0.0.1:8082

Queue-based security and triggering auto-registration

When a queue manager accesses a remote queue or any local queue that is defined with an attribute including the MQeWTLSCertAuthenticator, then the queue manager and queues are authenticatable entities and require their own credentials.

A queue manager's credentials are created by triggering auto-registration. The simplest way of triggering auto-registration is to include the relevant keywords in the registry section of the ini file used when the queue manager is created. The keywords needed on the command line are:

-c 22345678 -k It_is_a_secret -s FastNetwork:127.0.0.1:8082
 

The credentials of queues (with an attribute including MQeWTLSCertAuthenticator) are also created by triggering auto-registration. This happens automatically when an administration message adding the queue is processed providing that:

When adding a queue (with an attribute including MQeWTLSCertAuthenticator) the queue can have its own credentials or it can share its owning queue manager's credentials. This choice is determined when the 'create queue' administration message is constructed.

The following describes how to create a queue with name ServerTestQWTLS on ServerQMgr.

Assume that the mini-certificate server administrator has added ServerQMgr+ServerTestQWTLS2 with Certificate Request PIN equal to 12345678, and has started the mini-certificate server in 'server' mode. Use the -o flag on a q_create command to create queue ServerTestQWTLS2 as in the following example:

q_create ServerQMgr ServerTestQWTLS2 -o -p 12345678 -c 12345678 -k It_is_a_secret 
                                     -s FastNetwork:127.0.0.1:8082

Where the 12345678 following -c is ServerTestQWTLS2's Certificate Request PIN (not ServerQMgr's). Effectively, the -o flag causes the MQE_QUEUE_TARGETREGISTRY field in the queue creation administration message to be set to MQE_QUEUE_REGISTRYQUEUE, which means that the queue to be created should have its own credentials. (If the queue to be created is sharing its queue manager's credentials, MQE_QUEUE_TARGETREGISTRY must be set to MQE_QUEUE_REGISTRYQMGR. If the queue to be created is not having credentials, MQE_QUEUE_TARGETREGISTRY must be set to MQE_QUEUE_REGISTRYNONE.) The -o also causes the obtained credentials to be published in the queue manager's public registry.

Queue-based security, starting queue managers with private registries

Whenever a queue manager and any of its queues are authenticatable entities, that is, have their own credentials, then, in order to access these credentials, the appropriate parameters are needed when the queue manager is started.

While hard coding these parameters in the registry section of the appropriate ini file is a convenient mechanism during solution development, it is inappropriate for a production system. Whenever possible, these parameters should be collected interactively and used to start a queue manager instance without storing them in a file.



© IBM Corporation 2000, 2003. All Rights Reserved