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.
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.
WebSphere MQ Everyplace supplies two alternative attributes for message-level security.
A typical MQeMTrustAtribute protected message has the format:
RSA-enc{SymKey}, SymKey-enc {Data, DataDigest, DataSignature}
where:
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.
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.
/*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 */ } ... }
/* 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);
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 */ } }
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 */ } }