WS-S ECURITY E NCRYPTION & D ECRYPTION

Similarly to digital signatures, encryption use PKI keys and certificates for encryption and decryption.

When encrypting a message, the recipient's public key is used; only the private key can decrypt the message.

3.3.1 Encrypting the SOAP body

__74. In the Configure Multi-Protocol Gateway form, click the ellipsis (…) in the Multi-Protocol Gateway Policy field to open the policy editor.

__75. Drag an Encrypt action to the right of the sign action.

__76. Double click the encrypt action to complete its configuration.

__77. In the Configure Encrypt Action form, locate the Recipient Certificate field, then select DataPowerCryptoCert.

__78. Click the Done button.

__79. Click the Apply Policy button in the policy editor.

__80. In the command window, type the following command, replacing the NN with your student number. Make sure to include the /xml path in the URI.

post soapMsg.xml http://datapower:444nn/xml

Look closely at the output in the window. You should notice that the body of the SOAP message is encrypted.

Now you'll add a decrypt action to the policy.

__81. Back in the policy editor, in the Configured Rules section, click on the VerifyRule to make it the active rule in the editor.

__82. Drag a Decrypt action in front of the verify signature action. Since the original message is signed then encrypted, you need to perform the decrypt then verify (otherwise the verify step will fail).

__83. Double click the yellow outlined decrypt action.

__84. In the Decrypt Key field, select: DataPowerCryptoKey. (Notice that this is the key and not the cert).

__85. Click the Done button.

__86. Click the Apply Policy button.

__87. Click the Close Window link to close the policy editor.

__88. Click the Apply button in the main configuration page to apply all the changes to the service.

3.3.2 The Transaction Probe

So far, the processing rules that you've created have been relatively simple, but even with simple rules, sometimes you don't get the results you expect. The transaction probe provides a very powerful way to determine which action may be at fault. The probe provides an execution trace and snapshot of each action in the processing rule.

__89. In the Configure Multi-Protocol Gateway form, towards the upper right corner, click on the Show Probe link.

__90. In the probe window, click on the Enable Probe button.

__91. Click the Close button in the completion dialog.

__92. Post the SOAP message to your service again, and save the output in another file.

In the command window, type the following command, replacing the NN with your student number. Make sure to include the /xml path in the URI.

post soapMsg.xml http://datapower:444nn/xml > enc.xml

__93. If you like, you can use the type command to view the file to see that it has been digitally signed and encrypted.

__94. Now post the new signed and encrypted file. The results should be the original SOAP message, unencrypted without the digital signature.

post enc.xml http://datapower:444nn

__95. Look back at the probe window; click the Refresh button. You should see two transactions in the list.

The transaction list shows the two transactions you just posted and which rule was executed (based on the match rules). You can see that the first transaction properly processed by DemoRule, and the second transaction was processed by VerifyRule.

__96. Click on the magnifying glass on the first transaction.

In the top section of the window, there's an icon representing each of the actions in the processing rule you created. In front of each action icon is a magnifying glass. Clicking on the magnifying glass will reveal what the input to that action was. When the leftmost magnifying glass is selected, the original inbound XML document is shown.

__97. Click on the magnifying glass in front of the transform action.

The XML document shown in the window shows what will be fed into the transform action as the context document. Notice that the <encoded-description> tag still exists and contains base-64 encoded data.

__98. Click on the magnifying glass after the transform action (in front of the sign action).

This shows the results of the transform action and what is going to be fed into the sign action.

Notice now that the <encoded-description> element has been replaced with a <description>

element and that the text is no longer base-64 encoded. The <benefits> element has also been tokenized into a smaller XML tree.

__99. Click on the magnifying glass after the sign action.

Now the window shows a document that contains the digital signature. If you scroll the window down, you will notice that the SOAP body is still in clear text.

__100. Click on the magnifying glass after the encrypt action.

Now the entire body of the SOAP message has been encrypted.

__101. Close the transaction window.

__102. Close the probe window.

__103. If your configuration is working properly, click the Save Config link in the top navigation bar.

3.3.3 Field Level Encryption

In the previous steps, you saw how to encrypt the entire SOAP body. In some circumstances, it may be preferable to encrypt only specific elements.

Now you’ll modify the encrypt action so that only the <brand> tag will be encrypted.

__104. Re-open the policy editor by clicking on the ellipsis button in the Multi-Protocol Gateway Policy field.

__105. In the policy rule, double click the encrypt action to open its configuration settings.

__106. In the Message Type section, choose Selected Elements. When you make this selection, a new field, Document Crypto Map will appear.

The Document Crypto Map is used to tell the encryption action which element(s) are to be encrypted.

Since the document will be in XML, the most natural way of selecting the target elements is with XPath expressions. The Document Crypto Map represents a collection of XPath expressions which identify the elements to be encrypted.

__107. Click the plus (+) button next to the Document Crypto Map dropdown.

__108. For the Name field, type: MyCryptoMap

__109. For the Operation, make sure Encrypt (WS-Security) is selected.

__110. In the XPath Expression field, type //brand and then click the Add button to add this XPath to the list of expressions.

__111. Click the Apply button.

__112. Click the Done button in the Configure Sign Action window.

__113. Click the Apply Policy button in the policy editor.

__114. Click the Close Window link to close the policy editor.

__115. Click the Apply button in the main configuration form.

__116. In the command window, type the following command, replacing the NN with your student number. Make sure to include the /xml path in the URI.

post soapMsg.xml http://datapower:444nn/xml

Notice in the output that the SOAP body is no longer encrypted, however the <brand> element is now encrypted.

If you’re having a hard time reading the output from the command line, you can use the probe to view the formatted XML.