How to configure

This section shows how to configure a queue manager and a private registry with security features .

Setting up the queue manager

In order to configure a queue manager's private registry, which can be shared by its' queues, do the following:

  1. When starting the queue manager, present the private registry logon PIN. If auto-registration with a mini-certificate server is required, the CertReqPIN, KeyRingPassword, and CAIPAddrPort parameters must also be presented, on opening the registry.
  2. The mini-certificate server is running if auto-registration is required.

Setting up a private registry

A private registry is only relevant if one of the queue-attribute properties prerequisites it. In order to establish a queue manager private registry, which can be shared by its' queues, the following conditions must be met:

  1. The owning queue manager must itself have a registry of type private registry.
  2. The owning queue manager must have previously auto-registered with the mini-certificate server. This must have been primed to allow queue registry before the queue private registry can be established. if auto registration with a mini-certificate server is required.
  3. In starting the queue manager, the queue manager private registry logon PIN, CertReqPIN, KeyRingPassword, and CAIPAddrPort were passed whilst opening the registry. If a CertReqPIN different from the queue manager's is used for the queue, it is currently necessary to first shutdown the owning queue manager, replace the original CertReqPIN with the new one, and then start the queue manager again. Auto-registration will then be triggered using the new CertReqPIN when the queue private registry is activated first time.
  4. The mini-certificate server is running, if auto-registration with the mini-certificate server is required.

Refer to the WebSphere MQ Everyplace Application Programming Guide for operational details.

If queue private registry, instead of the queue manager's, is required, for example, the target registry property of the queue has been set to "Queue" for com.ibm.mqe.attributes.MQeWTLSCertAuthenticator.

Due to the intensity of numerical computation involved, auto-registration may take 10-20 minutes on a handheld device.

Setting up attribute properties

Security attribute properties can be added to a queue using the com.ibm.mqe.administration.MQeQueueAdminMsg class and its subclasses. The security attribute properties are defined as parameters of the administration message. The following example (examples.security.createSecureQueue) creates a new queue on an existing client queue manager. It creates the queue with a cryptor, compressor, authenticator, and attribute rule. It is not necessary to add all of these attributes and any of them could be omitted. A cryptor on a local queue uses a key seed based on the queue manager private registry logon PIN. Therefore, it is important to present the right PIN when starting the queue manager.

The example starts with a class header:

package examples.security;
 
import java.io.File;
import com.ibm.mqe.*;
import com.ibm.mqe.administration.*;
import examples.queuemanager.MQePrivateClient;
 
/** createSecureQueue.java
 * <p>This creates a secure queue on an existing queue manager. The queue is 
 * created with an authenticator, cryptor, compressor and attribute rule.
 * The queue manager must have a private registry, so that the queue can be
 * given a cryptor. 
 * 
 * <p>The program requires two command line parameters.
 * 
 * <p>The first parameter is a configuration file for the queue manager. This
 * is used to start the queue manager as a client. 
 * 
 * <p>The second parameter is the PIN for the queue manager's private
 * registry.
 * 
 **/
 
public class createSecureQueue
{
 

First we define the name of the queue we want to add:

  // the name of the queue
  String qName = "protQueue";

The attributes are defined by their class names:

  // define the attributes we want the queue to have. These are defined by
  // their class names.
  String cryptorType       = "com.ibm.mqe.attributes.MQeDESCryptor";
  String compressorType    = "com.ibm.mqe.attributes.MQeGZIPCompressor";
  String authenticatorType = "examples.attributes.NTAuthenticator";
  String attributeRule     = "com.ibm.mqe.MQeAttributeRule";

They are followed by some definitions of local variables:

  //local variables
  MQePrivateClient client;
  MQeQueueManager  clientQM;
  String           clientQMName;
  MQeQueueAdminMsg msg;

The example adds the queue directly to the local queue manager, so the queue manager must be activated:

  /**
   * open the queue manager as a client
   * 
   * @param configFile the configuration (.ini) file for the queue manager
   * @param qmPIN      the PIN for the queue manager's registry
   * @exception  java.lang.Exception  propagated from invoked methods
   **/
  void openQM(String configFile, String qmPIN) throws Exception
  {
    // start the queue manager as a client
    client = new MQePrivateClient(configFile, qmPIN, null, null);
 
    //save the queue manager and its name
    clientQM = client.queueManager;
    clientQMName = clientQM.getName();
  }
 

The MQeQueueAdminMsg is created and values added to it as normal. A correlation id is added to the message to make it easy to find the reply message. All the security attributes are added as parameters to the message, that is, they are added to a separate MQeFields object which is passed to the msg.create(parms) method:

  /**
   * create the admin message to add the queue attributes
   * 
   * @exception  java.lang.Exception  propagated from invoked methods
   **/
  void createAdminMsg() throws Exception
  {
    // the file descriptor
    String FileDesc = "MsgLog:.";
 
    // create an Admin msg to add the queue
    msg = new MQeQueueAdminMsg();
    msg.setTargetQMgr(clientQMName);
    msg.setName(clientQMName, qName);
    msg.putInt(MQe.Msg_Style, MQe.Msg_Style_Request);
    msg.putAscii(MQe.Msg_ReplyToQ, MQe.Admin_Reply_Queue_Name);
    msg.putAscii(MQe.Msg_ReplyToQMgr, clientQMName);
    msg.putArrayOfByte(MQe.Msg_CorrelID, 
				Long.toHexString(clientQM. uniqueValue()).getBytes());
 
    // define parameter values for the queue
    MQeFields parms = new MQeFields();
    parms.putUnicode(msg.Queue_Description, "DES protected queue");
    parms.putAscii(msg.Queue_FileDesc, FileDesc );
 
    // this is where we specify the queue attributes
    parms.putAscii(msg.Queue_Cryptor, cryptorType);
    parms.putAscii(msg.Queue_Compressor, compressorType);
    parms.putAscii(msg.Queue_Authenticator, authenticatorType); 
    parms.putAscii(msg.Queue_AttrRule, attributeRule);
    
    //add the parameters to the message
    msg.create(parms);
  }
 

The message is sent to the Admin Queue on the local queue manager:

  /**  
   * send the admin message to the client queue manager
   * 
   * @exception  java.lang.Exception  propagated from invoked methods
   **/
  void sendAdminMsg() throws Exception
{
    // send the Admin msg
    System.out.println("putting Admin Msg to QM/queue:" +
    clientQMName + "/" + MQe.Admin_Queue_Name);
    clientQM.putMessage(clientQMName, MQe.Admin_Queue_Name, msg, null, 0);
  }
 

The correlation id is used in a filter to find the correct reply. The example waits up to 3 seconds for the reply:

  /**
   * wait for a reply message and process it to determine success or failure
   * 
   * @exception  java.lang.Exception  propagated from invoked methods
   **/
  void processReply() throws Exception
    {
    // use the CorrelID to create a filter for the reply message
    MQeFields replyFilter = new MQeFields();
    replyFilter.putArrayOfByte(MQe.Msg_CorrelID,
     msg.getArrayOfByte(MQe.Msg_CorrelID));
 
    // get the Admin Reply msg
    MQeMsgObject reply = clientQM.waitForMessage(clientQMName,
                MQe.Admin_Reply_Queue_Name,
                replyFilter,
                null,
                0,
3000);
    if (reply instanceof MQeAdminMsg)
    {
      MQeAdminMsg adminReply = (MQeAdminMsg)reply;
      System.out.println("Admin Reply Msg received");
      if (adminReply.getRC() == MQeAdminMsg.RC_Success)
        System.out.println("Queue added OK");
      else
System.out.println("create Queue failed:" +
    adminReply.getReason());
    }
    else
      System.out.println("reply message is not an admin message");
  }
 

The queue manager needs to be closed:

  /**
   * close the queue manager
   * 
   * @exception  java.lang.Exception  propagated from invoked method
   **/
  void close() throws Exception
  {
    clientQM.close();
  }
 

The main() method for the example is:

  /**
   * main method.
   * 
   * @param  args  The command line arguments. The first is a configuration
   *               (.ini) file for the queue manager, the second is the PIN
   *               for the queue manager's private registry.
   * 
   **/
  public static void main(String [] args)
  {
    createSecureQueue secQueue = new createSecureQueue();
    // check the command line arguments
    if (args.length < 2)
      System.err.println("usage: createSecureQueue configFile qmPIN");
    else
    {
      try
      {
        secQueue.openQM(args[0], args[1]);
        secQueue.createAdminMsg();
        secQueue.sendAdminMsg();
        secQueue.processReply();
        secQueue.close();
      }
      catch (Exception e)
      {
        System.out.println("Exception caught:" + e);
      }
    }
  }
}
 

Attribute rules can also be set on channels using the ChannelAttrRules keyword in the configuration file used at queue manager creation time. WebSphere MQ Everyplace defaults the keyword to com.ibm.mqe.MQeAttrubuteRule.



© IBM Corporation 2002. All Rights Reserved