Overview

Skill Level: Beginner

Basic knowledge DataPower, Multi-Protocol Gateway service, and xslt is a plus.

This tutorial goes over creating a DataPower Multi-Protocol Gateway (MPGW) Service, which will take an input value and encrypt/decrypt it with a symmetric AES-256 cryptographic key.

Ingredients

  • OpenSSL available to geenerate the secret key.
  • Postman to test.
  • Developer privileges to DataPower should suffice. Access required to create a MPGW, create a crypto shared key object, assign a front side handler, and upload files.

 

Step-by-step

  1. Create the EncryptDecrypt MPGW Processing Policy and Rules

    This section will create the Processing Policy, and Processing Rules with the required Actions to be used in the MPGW later.

    1. Log into IBM DataPower under the domain that the EncryptDecrypt service will reside.
    2. Once logged in, remove the “/dp/login.xml” from the url and press enter to get into the old interface which screenshots from this tutorial will use.
      00.webuilogin
    3. Navigate into the File Management section filemanagement-1 and create a sub-directory titled EncryptDecrypt and upload the Encrypt.xsl and Decrypt.xsl found in the github repo.
      Note: If the repo does not work, the code is located in the appendix.
      filemanagementPreReq-2

     

    Create the EncryptDecrypt MPGW Processing Policy and Rules

    1. Once on the main page of DataPower, type policy into the search field to locate and select the Multi-Protocol Gateway Policy.
      05.policy
    2. Click on Add New Policy to create the new service policy.
      06.newpolicy
    3. Name the policy EncryptDecryptPolicy and click Apply Policy
      07.policyname
    4. Click on New Rule, name it Encrypt_ProcessingRule, drop down the Rule Direction to select Client to Server.
      08.encrypt_processingrule
    5. Double click the Match Action icon, then in the Configure a Match Action pop up, click on the Add icon.
      In the Configure Matching Rule pop up, use the name encrypt and click the Add button.
      In the Edit Rules pop up, enter */encrypt* input the URL match field.
      Continue to Apply the pop up windows and click Done at the last pop up Configure a Match Action.
      09.encryptMatch
    6. Back in the Configure Multi-Protocol Gateway Style Policy, click on Apply Policy.
      10.halfwaycompletePolicy-1
    7. Drag the Transform Action in between the Match and Results Action. Double click on the Transform Action and when the Configure Transform with XSLT style sheet Action pop ups, drop down the Transform File items and select the local://EncryptDecrypt and Encrypt.xsl. Click Done.
      11.transformActionOnRule
    8. Back in the Configure Multi-Protocol Gateway Style Policy, drag and drop the Advanced Action icon ( AdvancedAction) after the Transform Action. Double click the Advanced Action and when the Configure Action pop ups, locate and select the Set Variable and click Next.
      12.setvar
    9. In the Configure Set Variable Action pop up, click on the Var Builder button on the Variable Name and uncollapse the Service Variables and select var://service/mpgw/skip-backside. The skip-backside variable loops back the rules proceeding action, so we will see the output of the Encrypt.xsl transformation responsed back to the caller.
      13.setvar_skipbackside
    10. Assign the Variable Assignment to 1 and click Done.
      14.setvar_skipbackside_varAssignment
    11. Click on Apply Policy back in the Configure Multi-Protocol Gateway Style Policy and your policy should look like the following.
      15.policywithencryptrule
    12. Create another rule for the Decrypt similary done for the Encrypt_ProcessingRule.
      Click on the New Rule button, name the new rule Decrypt_ProcessingRule, and drop down the Rule Direction selecting Client to Server.
      Double click the Match Action.
      In the Configure a Match Action pop up, click on the Add icon.
      In the Matching Rule pop up, name the rule decrypt, and click Add.
      In the Edit Rules pop up, input */decrypt* in the URL match field.
      Continue to click Apply, then Done to accept and get back to the Policy screen.
      16.decryptmatch
    13. Back in the Confirgure Multi-Protocol Gateway Style Policy panel, drag and drop a Transform action after the Match action and double click on the Transform action. When the Configure Transform with XSLT style sheet Action pops up, drop down the Transform file to choose local:///EncryptDecrypt and Decrypt.xsl. Click Done and Apply Policy when complete.
      17.decrypttransformaction
    14. Back in the Confirgure Multi-Protocol Gateway Style Policy panel, drag and drop an Advanced action after the Transform action. Double click the Advance action, locate, and select the Set Variable. Click Next
      18.decryptSetVar
    15. In the Configure Set Variable Action pop up, click on the Var Builder for the Variable Name, collapse the Service Variables, to locate and select var://service/mpgw/skip-backside.
      Input 1 for the Variable Assignment and click Done.
      19.SetVarSkipbackside
    16. Then back in the main Configure Multi-Protocol Gateway Style Policy panel, click on Apply Policy and your policy should look like the following.
      20.encryptdecryptpolicycomplete

     

  2. Create the HTTP Front Side Handler

    This section will create the HTTP Front Side Handler which will be used in the overall MPGW later.

    1. Navigte to the HTTP Handler section and add a new HTTP handler.
      21.fsh_
    2. Name the HTTP Front Side Handler as HTTPFSH_EncryptDecrypt or a desired name, set the local IP address to 0.0.0.0 or specific interface you would like to use, set the port to 8888 or to the port you would like to use, and check the GET method under the Allowed methods and versions section.
      22.fsh_settings
  3. Create the Shared Secret Key and Share Secret Object

    The EncryptDecrypt MPGW contains stylesheets which will use the Crypto Shared Secret Key object to encrypt and decrypt the input.

    1. Generate the secret key via OpenSSL with the following command: openssl enc -aes-256-cbc -k secret -P -md sha256

      Yielding the output which looks like the following:
      24.secretkey
    2. Take the key value and append a 0x in front which will turn it into a hex-encoded string: “0xC7B8BC73C5B0043A7055F47CEFD1867406A6561636B3F1A94DC3FB5D42DB4106”
      Then save that to a file e.g. EncryptDecrypt_OpenSSL_Key.key
    3. Search and navigate over to the Crypto Shared Secret Key object and click Add.
      25.cryptosharedkey
    4. Enter EncryptDecryptKey for the name, and upload the EncryptDecrypt_OpenSSL_Key.key and Apply.
      26.secretkeyobject
  4. Create the EncryptDecrypt MPGW Service and put it altogether

    This step will walk through creating the EncryptDecrypt MPGW Service and put together the previous objects created.

    1. Navigate to the main DataPower screen.
    2. Click on the Multi-Protocol Gateway icon.
      mpgw
    3. Create a new MPGW.
      01.NewMPGW
    4. Name the MPGW (e.g. EncryptDecryptMPGW), set the Type to dynamic-backends, set the Request Type and Response Type to XML
      Drop down the Multi-Protocol Gateway Policy and select the created EncryptDecryptPolicy.
      In the Front Side Protocol section, drop down, select, and Add the HTTPFSH_EncryptDecrypt (HTTP Handler).
      23.mpgw_complete

     

  5. Testing

    You may download the Postman exports linked below or build out the request yourself, but here are the encryption and decryption tests against the service.

    Postman EncryptDecrypt Service Export

    Ensure you change the URL and Port (if changed in the service).

    postman_variables

    Encryption Test:

    27.request

     

    Decrypt Test:

    28.decrypt

  6. Appendix

    Encrypt.xsl

    <xsl:stylesheet 
    version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:dp="http://www.datapower.com/extensions"
    xmlns:dpconfig="http://www.datapower.com/param/config"
    xmlns:apim="http://www.ibm.com/apimanagement"
    xmlns:webapi="http://www.ibm.com/apimanagement"
    xmlns:func="http://exslt.org/functions"
    xmlns:wxsl="http://www.w3.org/1999/XSL/TransformAlias"
    xmlns:exsl="http://exslt.org/common"
    extension-element-prefixes="dp dpconfig exsl apim"
    exclude-result-prefixes="wxsl func dp">

    <xsl:template match="/">
    <xsl:variable name="vAlgorithm" select="'http://www.w3.org/2001/04/xmlenc#aes256-cbc'"/>
    <xsl:variable name="vPlainText" select="//*[local-name()='ClearText']"/>
    <xsl:variable name="vKey" select="'name:EncryptDecryptKey'"/>

    <!-- The console log for the text and key are commented out to ensure the logs will not capture the plain text or key, but you may uncomment for debugging. -->
    <!-- <xsl:message>****PlainText: <xsl:value-of select="$vPlainText"/>
    </xsl:message>
    <xsl:message>****Key: <xsl:value-of select="$vKey"/>
    </xsl:message> -->
    <xsl:message>****Algorithm: <xsl:value-of select="$vAlgorithm"/>
    </xsl:message>

    <xsl:variable name="vCipherString">
    <xsl:value-of select="dp:encrypt-string($vAlgorithm,$vKey,$vPlainText)"/>
    </xsl:variable>

    <encryptResponse>
    <encryptedText>
    <xsl:value-of select="$vCipherString"/>
    </encryptedText>
    </encryptResponse>

    </xsl:template>
    </xsl:stylesheet>

     

    Decrypt.xsl

    <?xml version="1.0" encoding="utf-8"?>
    <xsl:stylesheet
    version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:dp="http://www.datapower.com/extensions"
    xmlns:dpconfig="http://www.datapower.com/param/config"
    xmlns:apim="http://www.ibm.com/apimanagement"
    xmlns:webapi="http://www.ibm.com/apimanagement"
    xmlns:func="http://exslt.org/functions"
    xmlns:wxsl="http://www.w3.org/1999/XSL/TransformAlias"
    xmlns:exsl="http://exslt.org/common"
    extension-element-prefixes="dp dpconfig exsl apim"
    exclude-result-prefixes="wxsl func dp">

    <xsl:template match="/">
    <xsl:variable name="vAlgorithm" select="'http://www.w3.org/2001/04/xmlenc#aes256-cbc'"/>
    <xsl:variable name="vKey" select="'name:EncryptDecryptKey'"/>
    <xsl:variable name="vEncryptedText" select="//*[local-name()='EncryptedText']"/>

    <xsl:message>****Encrypted Text: <xsl:value-of select="$vEncryptedText"/>
    </xsl:message>
    <xsl:message>****Algorithm: <xsl:value-of select="$vAlgorithm"/>
    </xsl:message>
    <!-- The console log for the text and key are commented out to ensure the logs will not capture the plain text or key, but you may uncomment for debugging. -->
    <!--<xsl:message>****Key: <xsl:value-of select="$vKey"/>
    </xsl:message>-->

    <xsl:variable name="vDecrypt">
    <xsl:value-of select="dp:decrypt-data($vAlgorithm,$vKey,$vEncryptedText)"/>
    </xsl:variable>

    <decryptedResponse>
    <decryptedText>
    <xsl:value-of select="$vDecrypt"/>
    </decryptedText>
    </decryptedResponse>
    </xsl:template>
    </xsl:stylesheet>

     

     

     

    Complete DataPower Export of the EncryptDecrypt service with Shared Secret

    The export contains the DataPower export of the service creation described in this article. The Crypto Shared Secret is also included in the export, therefore, you’ll just have to import and test with postman.

    NOTICE: the port assigned to this service is 8888, therefore if there is anything assigned to port 8888, then you will have to update the HTTP FSH, and make sure you update the Postman testing port also.

    https://github.com/ibmArtifacts/encryptdecypt/blob/master/EncryptDecrypt_MPGW.zip 

2 comments on"IBM DataPower: Encryption and Decryption Multi-Protocol Gateway Service"

  1. Steven Harris November 30, 2020

    There is a minor flaw in the encryption transform. It produces XML containing something like. payload
    If you cut and paste this into Postman to test the decryption, it fails. The decryption transform expects payload as input and will fail if the first character of the tag is not capitalized.
    Wasted a couple of hours before I found the issue.

  2. Steven Harris November 30, 2020

    In my last comment the xml tags were stripped out. The encryption transform produces encryptedText tags, but decryption expects EncryptedText

Join The Discussion