Message-level security

Message-level security facilitates the protection of message data between an initiating and receiving WebSphere MQ Everyplace application. Message-level security is an application layer service. It requires the initiating WebSphere MQ Everyplace application to create a message-level attribute and provide it when using putMessage() to put a message to a target queue.

The receiving application must set up and pass a matching message-level attribute to the receiving queue manager so that the attribute is available when the application invokes getMessage() to get the message from the target queue.

Like local security, message-level security exploits the application of an attribute on a message, an MQeFields object descendent. The initiating application's queue manager handles the application's putMessage() with the message Java dump method or C API, which invokes the attached attribute's Java encodeData() method or C API to protect the message data. The receiving application's queue manager handles the application's getMessage() with the message's Java 'restore' method or C API, which in turn uses the supplied attribute's decodeData() method to recover the original message data.

Usage scenario

Message-level security is typically most useful for:

A typical scenario is a solution service that is delivered over multiple open networks. For example over a mobile network and the internet, where, from outset asynchronous operation is anticipated. In this scenario, it is also likely that message data is flowed over multiple links that may have different security features, but whose security features are not necessarily controlled or trusted by the solution owner. In this case it is very likely the solution owner does not wish to delegate trust for the confidentiality of message data to any intermediate, but would prefer to manage and control trust management directly.

WebSphere MQ Everyplace message-level security provides solution designers with the features that enable the strong protection of message data in a way that is under the direct control of the initiating and recipient applications, and that ensures the confidentiality of the message data throughout its transfer, end to end, application to application.

Secure feature choices

WebSphere MQ Everyplace supplies two alternative attributes for message-level security.

MQeMAttribute
This suits business-to-business communications where mutual trust is tightly managed in the application layer and requires no trusted third party. It allows use of all available WebSphere MQ Everyplace symmetric cryptor and compressor choices. Like local security it requires the attribute's key to be preset before it is supplied as a parameter on putMessage() and getMessage(). This provides a simple and powerful method for message-level protection that enables use of strong encryption to protect message confidentiality, without the overhead of any public key infrastructure (PKI).
MQeMTrustAttribute
Note:
The MQeMTrustAttribute does not apply to the C codebase.
This provides a more advanced solution using digital signatures and exploiting the default public key infrastructure to provide a digital envelope style of protection. It uses ISO9796 digital signature or validation so that the receiving application can establish proof that the message came from the purported sender. The supplied attribute's cryptor protects message confidentiality. SHA1 digest guarantees message integrity and RSA encryption and decryption, ensuring that the message can only be restored by the intended recipient. As with MQeMAttribute, it allows use of all available WebSphere MQ Everyplace symmetric cryptor and compressor choices. Chosen for size optimization, the certificates used are mini-certificates which conform to the WTLS Specification approved by the WAP forum. WebSphere MQ Everyplace provides a default public key infrastructure to distribute the certificates as required to encrypt and authenticate the messages.

A typical MQeMTrustAtribute protected message has the format:

 RSA-enc{SymKey}, SymKey-enc {Data, DataDigest, DataSignature}

where:

RSA-enc:
RSA encrypted with the intended recipient's public key, from his mini-certificate
SymKey:
Generated pseudo-random symmetric key
SymKey-enc:
Symmetrically encrypted with the SymKey
Data:
Message data
DataDigest:
Digest of message data
DigSignature:
Initiator's digital signature of message data

Selection Criteria

MQeMAttribute relies totally on the solution owner to manage the content of the key seed that is used to derive the symmetric key used to protect the confidentiality of the data. This key seed must be provided to both the initiating and recipient applications. While it provides a simple mechanism for the strong protection of message data without the need of any PKI, it clearly depends of the effective operational management of the key seed.

MQeMTrustAttribute exploits the advantages of the WebSphere MQ Everyplace default PKI to provide a digital envelope style of message-level protection. This not only protects the confidentiality of the message data flowed, but checks its integrity and enables the initiator to ensure that only the intended recipient can access the data. It also enables the recipient to validate the originator of the data, and ensures that the signer cannot later deny initiating the transaction. This is known as non-repudiation.

Solutions that wish to simply protect the end-to-end confidentiality of message data will probably decide that MQeMAttrribute suits their needs, while solutions for which one to one (authenticatable entity to authenticatable entity) transfer and non-repudiation of the message originator are important may find MQeMTrustAttribute is the correct choice.

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 */
   }
}