Usage guide

The following code fragments provide examples of how to protect and unprotect a message using MQeMAttribute, in both Java and C, and alsoMQeMTrustAttribute, which is Java specific.

Message-level security using MAttribute for Java

Note:
    /*SIMPLE PROTECT FRAGMENT */
{     
     MQeMsgObject msgObj = null;
     MQeMAttribute attr = null;
     long confirmId = MQe.uniqueValue();
     try{
        trace(">>>putMessage to target Q using MQeMAttribute"
	              +" with 3DES Cryptor and key=my secret key");
         /* create the cryptor */
        MQe3DESCryptor tdes = new MQe3DESCryptor();
         /* create an attribute using the cryptor */
        attr = new MQeMAttribute(null,tdes,null );
         /* create a local key */
        MQeKey localkey = new MQeKey();
         /* give it the key seed */
        localkey.setLocalKey("my secret key");
         /* set the key in the attribute */
        attr.setKey(localkey );
         /* create the message */
        msgObj = new MQeMsgObject();
        msgObj.putAscii("MsgData","0123456789abcdef...");
         /* put the message using the attribute */
        newQM.putMessage(targetQMgrName, targetQName,
				              msgObj, attr, confirmId );
        trace(">>>MAttribute protected msg put OK...");
       }
    catch (Exception e)
       {
       trace(">>>on exception try resend exactly once...");
       msgObj.putBoolean(MQe.Msg_Resend, true );
       newQM.putMessage(targetQMgrName, targetQName,
				                  msgObj, attr, confirmId );
       }
}
 
    /*SIMPLE UNPROTECT FRAGMENT */
{
       MQeMsgObject msgObj2 = null;
       MQeMAttribute attr2 = null;
       long confirmId2 = MQe.uniqueValue();
    try{
       trace(">>>getMessage from target Q using MQeMAttribute"+
	          " with 3DES Cryptor and key=my secret key");
        /* create the attribute - we do not have to specify the cryptor, */
        /* the attribute can get this from the message itself  */
       attr2 = new MQeMAttribute(null,null,null );
        /* create a local key */
       MQeKey localkey = new MQeKey();
        /* give it the key seed */
       localkey.setLocalKey("my secret key");
        /* set the key in the attribute */
       attr2.setKey(localkey );
        /* get the message using the attribute */
       msgObj2 = newQM.getMessage(targetQMgrName, targetQName, 
                                  null, attr2, confirmId2 );
       trace(">>>unprotected MsgData = "
	          + msgObj2.getAscii("MsgData"));
       }
    catch (Exception e)
      {					
       /*exception may have left */
      newQM.undo(targetQMgrName,	           
		/*message locked on queue */
	              targetQName, confirmId2 );	
		/*undo just in case */
      e.printStackTrace();	                 
		/*show exception reason */
      }
     ...
}

Message-level security using MAttribute for C

  	/* putMessage */
   MQeMsgAttrHndl    hAttr = NULL;
   MQeStringHndl     hKeySeed = NULL, hQMgrName = 
													NULL, hQName = NULL;
   MQeStringHndl     hFieldName = NULL, hFieldData = NULL;
   MQeExceptBlock    exceptBlock;
   MQeFieldsHndl     hData = NULL;
   MQeQueueManagerHndl hQMgr = NULL;
   MQERETURN rc;
 
   ...
   /* assume queue manager handle in hQMgr, 
	/*QMgr name in hQMgrName, and queue name in hQName */
 
   /* create a key seed string */
   rc = mqeString_newChar8(&exceptBlock, &hKeySeed, 
										"my secret key");
   /* create a new attribute with a RC4 cryptor */
   rc = mqeMsgAttr_new(&exceptBlock, &hAttr, NULL, 
									MQE_RC4_CRYPTOR_CLASS_NAME, 
									NULL, hKeySeed);
   /* create a data Fields */
   rc = mqeFields_new(&exceptBlock, &hData);
   /* add some test data */
   rc = mqeString_newChar8(&exceptBlock, &hFieldName, 
										"MsgData");
   rc = mqeString_newChar8(&exceptBlock, &hFieldData, 
										"0123456789abcdef....");
   rc = mqeFields_putAscii(hData, &exceptBlock, 
										hFieldName, hFieldData);
   /* send message */
   rc = mqeQueueManager_putMessage(hQMgr, &exceptBlock, 
													hQMgrName, hQName, 
													hData, hAttr, 0);
 
   /* getMessage */
   MQeMsgAttrHndl hAttr = NULL;
   MQeStringHndl     hKeySeed = NULL, hQMgrName = 
													NULL, hQName = NULL;
   MQeStringHndl     hFieldName = NULL, hFieldData = NULL;
   MQeExceptBlock    exceptBlock;
   MQeQueueManagerHndl hQMgr = NULL;
   MQERETURN rc;
 
   ...
   /* assume queue manager handle in hQMgr, QMgr 
			name in hQMgrName, and queue name in hQName */
 
   /* create a key seed string */
   rc = mqeString_newChar8(&exceptBlock, &hKeySeed, 
										"my secret key");
   /* create a new attribute with a RC4 cryptor */
   rc = mqeMsgAttr_new(&exceptBlock, &hAttr, NULL, 
									MQE_RC4_CRYPTOR_CLASS_NAME, 
									NULL, hKeySeed);
   /* get message */
   rc = mqeQueueManager_getMessage(hQMgr, &exceptBlock, 
												&hData, hQMgrName, 
												hQName, NULL, hAttr, 0);
   /* get test data */
   rc = mqeString_newChar8(&exceptBlock, &hFieldName, 
										"MsgData");
   rc = mqeFields_getAscii(hData, &exceptBlock, 
										&hFieldData, hFieldName);
 

Message-level security using MTrustAttribute (Java only)

For an explanation about MQePrivateRegistry and MQePublicRegistry, used in the following example, refer to Private registry serviceand Public registry service.

    /*SIMPLE PROTECT FRAGMENT */
{
    MQeMsgObject msgObj = null;
    MQeMTrustAttribute attr = null;
    long confirmId = MQe.uniqueValue();
try {
    trace(">>>putMessage from Bruce1 intended for Bruce8" 
	       + " to target Q using MQeMTrustAttribute 
					with MARSCryptor ");
     /* create the cryptor */
    MQeMARSCryptor mars = new MQeMARSCryptor();
     /* create an attribute using the cryptor */
    attr = new MQeMTrustAttribute(null, mars, null);
     /* open the private registry belonging to the sender */
    String EntityName = "Bruce1";
    String PIN = "12345678";
    Object Passwd = "It_is_a_secret";
    MQePrivateRegistry sendreg = new MQePrivateRegistry();
    sendreg.activate(EntityName, ".\\MQeNode_PrivateRegistry",
                     PIN, Passwd, null, null );
     /* set the private registry in the attribute */
    attr.setPrivateRegistry(sendreg );
     /* set the target (recipient) name in the attribute */
    attr.setTarget("Bruce8");
     /* open a public registry to get the target's certificate */
    MQePublicRegistry pr = new MQePublicRegistry();
    pr.activate("MQeNode_PublicRegistry", ".\\");
     /* set the public registry in the attribute */
    attr.setPublicRegistry(pr);
     /* set a home server, which is used to find the certificate*/
     /* if it is not already in the public registry */
    attr.setHomeServer(MyHomeServer +":8082");
     /* create the message */
    msgObj =new MQeMsgObject();
    msgObj.putAscii("MsgData","0123456789abcdef...");
     /* put the message using the attribute */
    newQM.putMessage(targetQMgrName, targetQName,
                     msgObj, attr, confirmId );
    trace(">>>MTrustAttribute protected msg put OK...");
    }
catch (Exception e)
    {
    trace(">>>on exception try resend exactly once...");
    msgObj.putBoolean(MQe.Msg_Resend, true);
    newQM.putMessage(targetQMgrName, targetQName,
                     msgObj, attr, confirmId );
    }
}
 
 
    /*SIMPLE UNPROTECT FRAGMENT */
{
    MQeMsgObject msgObj2 = null;
    MQeMTrustAttribute attr2 = null;
    long confirmId2 = MQe.uniqueValue();
try {
    trace(">>>getMessage from Bruce1 intended for Bruce8"
	       + " from target Q using MQeMTrustAttribute with MARSCryptor ");
     /* create the cryptor */
    MQeMARSCryptor mars = new MQeMARSCryptor();
     /* create an attribute using the cryptor */
    attr2 = new MQeMTrustAttribute(null, mars, null);
     /* open the private registry belonging to the target */
    String EntityName =  "Bruce8";
    String PIN =  "12345678";
    Object Passwd =  "It_is_a_secret";
    MQePrivateRegistry getreg = new MQePrivateRegistry();
    getreg.activate(EntityName, ".\\MQeNode_PrivateRegistry",
                    PIN, Passwd, null, null );
     /* set the private registry in the attribute */
    attr2.setPrivateRegistry(getreg);
     /* open a public registry to get the sender's certificate */
    MQePublicRegistry pr = new MQePublicRegistry();
    pr.activate("MQeNode_PublicRegistry", ".\\");
     /* set the public registry in the attribute */
    attr2.setPublicRegistry(pr);
     /* set a home server, which is used to find the certificate*/
     /* if it is not already in the public registry */
    attr2.setHomeServer(MyHomeServer +":8082");
     /* get the message using the attribute */
    msgObj2 = newQM.getMessage(targetQMgrName,
                               targetQName, null, attr2, confirmId2 );
    trace(">>>MTrustAttribute protected msg = "
          + msgObj2.getAscii("MsgData"));
    }
catch (Exception e)
    {	
     /*exception may have left */
    newQM.undo(targetQMgrName,	           /*message locked on queue */
	            targetQName, confirmId2 );	/*undo just in case */
    e.printStackTrace();		              /*show exception reason */
    }
}

Non-repudiation

The MQeMTrustAttribute digitally signs messages. This enables the recipient to validate the creator of the message, and ensures that the creator cannot later deny creating the message. This is known as non-repudiation. This process depends on the fact that only one public key can validate the signature successfully generated by a particular private key. This validation proves that the signature was created with the corresponding private key. The only way the alleged creator can deny creating the message is to claim that someone else had access to the private key.

When a message is created with the MQeMTrustAttribute, it uses the private key from the sender's private registry to create the digital signature and it stores the sender's name in the message. When the message is read with the queue manager's getMessage() method, it uses the sender's public certificate to validate the digital signature. The message is read successfully only if the signature validates successfully, proving that the message was created by the entity whose name was stored in the message as the sender.

When the MQeMTrustAttribute is specified as a parameter to the queue manager's getMessage() method, the attribute validates the digital signature but by the time the message is returned to the user's application all the information relating to the signature has been discarded. If non-repudiation is important to you, you must keep a record of this information. The simplest way to do this is to keep a copy of the encrypted message, because that includes the digital signature. You can do this by using the getMessage() method without an attribute. This returns the encrypted message which you can then save, for example in a local queue. You can decrypt the message by applying the attribute to access the contents of the message.

The following code fragment provides an example of how to save an encrypted message.

Saving a copy of an encrypted message

/*SIMPLE FRAGMENT TO SAVE ENCRYPTED MESSAGE*/
{
MQeMsgObject msgObj2 = null;
MQeMTrustAttribute attr2 = null;
long confirmId2 = MQe.uniqueValue();
long confirmId3 = MQe.uniqueValue();
try {
    trace(">>>getMessage from Bruce1 
					intended for Bruce8"
	  + " from target Q using MQeMTrustAttribute 
			with MARSCryptor ");
    /* read the encrypted message without an attribute */
    MQeMsgObject tmpMsg1 = newQM.getMessage(targetQMgrName,
				    targetQName, null, null, confirmId2 );
    /* save the encrypted message - 
			we cannot put it directly */
    /* to another queue because of 
			the origin queue manager  */
    /* data. Embed it in another message */
    MQeMsgObject tmpMsg2 = new MQeMsgObject();
    tmpMsg2.putFields("encryptedMsg", tmpMsg1);
    newQM.putMessage(localQMgrName, archiveQName, 
								tmpMsg2, null, confirmId3);
    trace(">>>encrypted message saved locally");
    /* now decrypt and read the message & */
    /* create the cryptor */
    MQeMARSCryptor mars = new MQeMARSCryptor();
    /* create an attribute using the cryptor */
    attr2 = new MQeMTrustAttribute(null, mars, null);
    /* open the private registry belonging to the target */
    String EntityName =  "Bruce8";
    String PIN =  "12345678";
    Object Passwd =  "It_is_a_secret";
    MQePrivateRegistry getreg = new MQePrivateRegistry();
    getreg.activate(EntityName, 
					".\\MQeNode_PrivateRegistry",
					PIN, Passwd, null, null );
    /* set the private registry in the attribute */
    attr2.setPrivateRegistry(getreg);
    /* open a public registry to 
			get the sender's certificate */
    MQePublicRegistry pr = new MQePublicRegistry();
    pr.activate("MQeNode_PublicRegistry", ".\\");
    /* set the public registry in the attribute */
    attr2.setPublicRegistry(pr);
    /* set a home server, which is 
			used to find the certificate*/
    /* if it is not already in the public registry */
    attr2.setHomeServer(MyHomeServer +":8082");
    /* decrypt the message by unwrapping it */
    msgObj2 = tmpMsg1.unwrapMsgObject(attr2);
    trace(">>>MTrustAttribute protected msg = "
		+ msgObj2.getAscii("MsgData"));
 
catch (Exception e)
  {			/*exception may have left */
    newQM.undo(targetQMgrName, 
		/*message locked on queue */
	       targetQName, confirmId2 );	
		/*undo just in case */
    e.printStackTrace();		
		/*show exception reason */
   }
}
 
 
 


© IBM Corporation 2002. All Rights Reserved