Securing JSON payloads using WebSphere DataPower Appliances

Learn different methods to secure a JSON payload transmitted in a REST-based architecture. These methods preserve the privacy of the payload regardless of the transport protocol. You will also learn how to encrypt both the entire payload or only select elements.

Share:

David Shute, WebSphere DataPower Enablement Program Manager, IBM

Photo of David ShuteDavid Shute is a Program Manager with the DataPower team at the time of its acquisition by IBM. He has been working with DataPower technologies for eight years.



29 January 2014

Introduction

The increasing adoption of REST-based communications, driven by the adoption of lightweight mobile devices, creates the need to secure those communications. This is particularly true when a message contains a payload of information, typically formatted as JavaScript Object Notation (JSON) text.

This article demonstrates how to use WebSphere DataPower appliances running version 6.0.1.0 or later firmware to encrypt JSON payloads for transmission using the REST standards. This protects the privacy of messages independent of the transport method (such as SSL). We will demonstrate the following methods:

  • The entire payload is encrypted using the PKCS#7 standard.
  • Selected elements are encrypted using a shared secret key.
  • Selected elements are encrypted using asymmetrical keys (certificates and keys).

Both the encrypting (or sending) side of the transmission and the decrypting (or receiving) side of the transmission are demonstrated here.

This article also demonstrates the use of XQuery and JSONiq processing scripts to perform the encryption and decryption.

You can use the same Multi-Protocol Gateway service on both the sending and receiving end of the transmission; the static backend destination just needs adjustment.

Prerequisites

The article uses cryptographic keys and certificates. To complete these instructions without interruption, you must first create the cryptographic key and certificate objects.

Key and certificate pair

Follow these instructions to create the necessary key and certificate objects:

  1. Type Ident in the Search bar of the navigation pane.
  2. Click Cryptographic Identification Credentials.
  3. Click Add to create a new Identification Credential object.
  4. Enter Jason in the Name field as shown in Figure 1.
  5. Click the + button under Crypto Key. A new window opens.
  6. Enter Jason in the Name field.
  7. Upload a cryptographic key to complete this object. If you do not have a key, use the Crypto Tools available on the device to create a key.
  8. Click Apply. The window closes.
  9. Click + under the Certificate on the Identification Credentials page. A new window opens.
  10. Enter Jason in the Name field.
  11. Upload a cryptographic certificate object to complete this object. If you do not have a key, use the Crypto Tools available on the device to create a certificate.
  12. Click Apply. The window closes.
  13. Click Apply to complete the Cryptographic Identification Credentials object.
    Figure 1. Cryptographic Identification Credentials

Shared secret key

  1. Type Shared in the Search bar of the navigation pane.
  2. Click Cryptographic Shared Secret Key.
  3. Click Add to create a new key.
  4. Enter aes-128 in the Name field as shown in Figure 2. You are required to use this name.
  5. Upload the keyd.dat file from the materials provided with this article in the Download section, or upload your own symmetric key.
  6. Click Apply.
  7. Click Save Config.
    Figure 2. Cryptographic Shared Secret Key
    Cryptographic Shared Secret Key

Requesting a document

Here is the sample JSON document used for this article:

{
  "Name":"Cartoon Studios",
  "AccountID":"8458jf8757275234",
  "Social-no":"123-45-6789",
  "State":"MA"
}

The "Social-no" element value will be secured by performing the steps in this article.


Creating a destination

The service created in this article uses a destination that just returns what the service sends it, just like a mirror. To create such a destination, follow these steps:

  1. Type HTTP in the search field of the navigation bar. Select HTTP Service from the list that appears.
  2. Click Add to create a new service.
  3. Type Mirror in the Name field.
  4. Change the Port Number to 2049.
  5. Change the Mode to echo.
  6. Click Apply.
  7. Click Save Config.

Testing the configuration

After completion of each processing rule described here, you can test the new rule by sending a request to the Gateway.

To test the encrypting rules, send the plain JSON payload request.jsn to the Gateway. For example, here is a curl command:

curl –data-binary @request.jsn http://dp_addr:3333/ssn

To test the decryption rules, you first need to create an encrypted payload. You can do this by capturing the output of the encrypting rule. Here is an example using curl:

curl –data-binary @request.jsn http://dp_addr:3333/ssn > request-enc.jsn

curl –data-binary @request-enc.jsn http://dp_addr:3333/dssn

Debugging the configuration

Set the application domain system log level to "debug" to capture all possible debugging entries in the default system log. To do this, click on the Troubleshooting icon on the Control Panel. Under Logging, select debug from the Log Level dropdown list. Then click the Log Level button.


Configuring the Multi-Protocol Gateway service

All of the methods demonstrated here use a Multi-Protocol Gateway service to do the work. This section describes the configuration of this service (Figure 3), except for the Processing Policy.

  1. Type Multi in the search bar on the Navigation pane.
  2. Select New MultiProtocol Gateway from the list of possible entries.
  3. Enter or select the following values:
    • Name:SecureJSON
    • Default Backend URL:http://127.0.0.1:2049
    • Response Type: Pass-through
    • Request Type: Non-XML
    Figure 3. Multi-Protocol Gateway Initial Configuration
    Multi-Protocol Gateway Initial Configuration

    Click to see larger image

    Figure 3. Multi-Protocol Gateway Initial Configuration

    Multi-Protocol Gateway Initial Configuration
  4. On the Advanced tab of the Multi-Protocol Gateway (Figure 4), set Proxy HTTP Response to On. Return to the General tab.
    Figure 4. Multi-Protocol Gateway Advanced tab
    Multi-Protocol Gateway Advanced tab

Front Side Protocol Handler

  1. Under Front Side Protocol, click + to create a new Handler. Select HTTP Front Side Handler from the list that appears. In the Configure HTTP Front Side Handler window that opens, set the following values (Figure 5):
    • Name:HTTP3333
    • Port Number:3333
    • Allowed Methods: Click to add the GET method to the default list.
    Figure 5. Front Side Protocol Handler
    Front Side Protocol Handler

Finish the interim configuration

  1. Under Multi-Protocol Gateway Policy, select default. This policy is only a placeholder for use while the Gateway is completed.
  2. Click Apply to apply the settings of the new Gateway.
  3. Click Save Config.

Processing the policy configuration

Each of the three methods for applying encryption to JSON payloads are detailed here. You may want to do only those steps related to the method you want to use.

Note that the Gateway configuration uses a Request Type of Non-XML to allow the PKCS#7 Decryption rule to run successfully. If you are not going to use this rule, you can set the Gateway configuration Request Type to JSON. This causes the device to automatically check request documents to insure the documents are well-formed JSON. This is also more effective for the Probe.

PKCS#7 encryption

  1. Under Multi-Protocol Gateway Policy, click + to create a new policy.
  2. Enter SecureJSON for the Name of the policy as shown in Figure 6.
  3. Click New Rule.
  4. Change the name of the rule to SecureJSON_rule_pk7encrypt.
  5. Set the Rule Direction to Client to Server.
  6. Double-click the highlighted Match action icon.
    Figure 6. Initial processing policy
    Initial processing policy
  7. Click + to create a new Match.
  8. Enter ebin in the Name field as shown in Figure 7.
  9. Click the Matching Rule tab.
  10. Click Add.
  11. Type */ebin in the URL Match field.
  12. Click Apply. The window closes. The new rule is entered in the grid.
    Figure 7. ebin Matching Rule
    ebin Matching Rul
  13. Click Apply. The window closes.
  14. Click Done. The window closes. The blue Processing Policy pane is active again (Figure 8).
    Figure 8. Match Action
    Match Action
  15. Drag the Advanced action icon onto the processing line.
  16. Double-click the icon.
  17. Select Crypto Binary from the list of possible action types as shown in Figure 9.
    Figure 9. Select Crypto Binary Advanced Action
    Select Crypto Binary Advanced Action
  18. Click Next. A new window opens.
  19. Select PKCS#7 Encrypt from the list of possible Operations as shown in Figure 10.
  20. Select the certificate desired from the list of Recipients and click Add.
    Figure 10. PKCS#7 Encrypt
    PKCS#7 Encrypt
  21. Click Done. The window closes.
    Figure 11. PKCS#7 Encrypt Policy
    KCS#7 Encrypt Policy
  22. Click ApplyPolicy as shown in Figure 11. If this completes the policy configuration desired, click Close Window to close the Processing Policy window. Then click Apply on the Gateway page.

    When you submit the sample request document to this rule, you should receive a result similar to the following:

    ---BEGIN PKCS7-----
    MIIByQYJKoZIhvcNAQcDoIIBujCCAbYCAQAxgeAwgd0CAQAwRjA6MQswCQYDVQQG
    EwJVUzELMAkGA1UECBMCTUExDjAMBgNVBAcTBUtUb3duMQ4wDAYDVQQDEwVKYXNv
    bgIIBImBLUcGRo8wDQYJKoZIhvcNAQEBBQAEgYCHrd/qNEtgGZpXDK8yFLP65lO2
    yRVtIst3E/hOqFy4Jt2YWtfsjLP2nuL27fEv3C+iLQSQo5leJCBaWF83xqUb4rMA
    I+1/8+T19ciEm5u7JhPAJ17G2Ypd1jqquXeVeJq6Mo1jYqTKjMt+2ir8ijhhuX6/
    JzOIa+cAznBOD4+uaDCBzQYJKoZIhvcNAQcBMB0GCWCGSAFlAwQBAgQQ2LCVsgxa
    6alYZyGem0he2oCBoDbUr0nPULErHNfrk2twhBaPZzae3KUF07RYddamwBWBRkJe
    7/Z4QU9WR8n/GoPe0vq6gsxHAaGqWCBoI0HCY+YTV6aF7ARlg5n2bVHKEx8lsH6G
    fxWwoKJu6j/BSmJCcoYaJNc5fATxr8mFKMJV1GcQg666hwzx143GkcAHmaclXu9w
    awpqndNhpKAukj6vxWUU8aAr8AehRRYaFXWoYf4=
    -----END PKCS7-----

    The entire payload is encrypted. Save this result in a local file to submit to the rule that decrypts this payload, described in the next section.

PKCS#7 decryption

  1. Click New Rule.
  2. Change the name of the rule to SecureJSON_rule_pk7decrypt.
  3. Set the Rule Direction to Client to Server.
  4. Double-click the highlighted Match action icon.
  5. Click + to create a new Match.
  6. Enter dbin in the Name field as shown in Figure 12.
  7. Click the Matching Rule tab.
  8. Click Add.
  9. Type */dbin in the URL Match field.
  10. Click Apply. The window closes. The new rule is entered in the grid.
    Figure 12. dbin Matching Rule
    dbin Matching Rule
  11. Click Apply. The window closes.
  12. Click Done. The window closes. The blue Processing Policy pane is active again.
  13. Drag the Advanced action icon onto the processing line.
  14. Double-click the icon.
  15. Select Crypto Binary from the list of possible action types.
  16. Click Next. A new window opens.
  17. Select PKCS#7 Decrypt from the list of possible Operations as shown in Figure 13.
  18. Select PEM from the list of Input Encoding Formats.
  19. Select None from the list of Output Encoding Formats.
  20. Select the Crypto Identification Credential desired from the list of Recipients and click Add.
    Figure 13. PKCS#7 Decrypt
    PKCS#7 Decrypt
  21. Click Done. The window closes.
  22. Click Apply Policy. If this completes the policy configuration desired, click Close Window to close the Processing Policy window. Then click Apply on the Gateway page.

    If you submit the result of the rule you constructed above to encrypt the JSON payload, you should receive the original, plain text JSON document again.

    {
              "Name":"Cartoon Studios",
              "AccountID":"8458jf8757275234",
              "Social-no":"123-45-6789",
              "State":"MA"
    }

Element encryption using a shared secret key

You must create a Shared Secret Key cryptographic object in order to use this method. Follow the instructions in the Shared secret key section to create this key object if you have not already done so.

Follow these steps to use a shared secret key to encrypt elements of a JSON payload:

  1. Click New Rule.
  2. Change the name of the rule to SecureJSON_rule_ssencrypt.
  3. Set the Rule Direction to Client to Server.
  4. Double-click the highlighted Match action icon.
  5. Click + to create a new Match
  6. Enter ssn in the Name field.
  7. Click the Matching Rule tab.
  8. Click Add.
  9. Type */ssn in the URL Match field.
  10. Click Apply. The window closes. The new rule is entered in the grid as shown in Figure 14.
    Figure 14. ssn Match Rule
    ssn Match Rule
  11. Click Apply. The window closes.
  12. Click Done. The window closes. The blue Processing Policy pane is active again.
  13. Drag the Transform icon onto the processing line.
  14. Double-click the icon.
  15. Under Use Document Processing Instructions, select Transform with processing control file, if specified.
  16. The Input Language should be JSON, and the Transform Language should be Xquery.
  17. Click the Upload button under the Processing Control file, and upload the set-dp-var.xq file as shown in Figure 15.
    Figure 15. Configure Xquery Transform
    Configure Xquery Transform
  18. Click Done. The window closes. The Processing Policy window regains focus as shown in Figure 16.
    Figure 16. Shared Secret Encryption Policy - Step One
    Shared Secret Encryption Policy - Step One

    Here is the content of the set-dp-var.xq file:

    declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
    declare namespace dp = "http://www.datapower.com/extensions";
    declare option jsoniq-version "0.4.42";
    declare option output:method "json";
    
    let $ssn := .("Social-no")
    
    let $dono := dp:set-variable("var://context/mine/myvar1", $ssn)
    
    let $myvar := dp:variable("var://context/mine/myvar1")
    
    return
    
    jn:object(
     for $key in jn:keys(.)
     let $val := if ($key = "Social-no") then $myvar else .($key)
     return { $key : $val }
    )

    This script extracts the value of the Social-no JSON element from the submitted message, places it in a DataPower variable, and then uses that same variable to output the message again. The output of this transform is not important; it is the setting of the DataPower variable that is most important. This variable is used in the next step of the Processing Policy.

  19. Drag another Transform Action onto the Processing Rule.
  20. Double-click the icon.
  21. Under Use Document Processing Instructions, select Transform with XSLT stylesheet as shown in Figure 17.
  22. Upload the string-crypto-var.xsl file.
  23. Set the Output context to NULL.
    Figure 17. Configure Transform XSLT
    Configure Transform XSLT
  24. Click Done. The window closes.

    This stylesheet retrieves the value of the DataPower variable set in the previous step, encrypts it with the shared secret key, and places the result in a DataPower variable as shown below:

    <xsl:output method="xml"/>
    
    <xsl:template match="/">
        <xsl:variable name="ssn">
            <xsl:value-of select="dp:variable('var://context/mine/myvar1')" />
        </xsl:variable>
    
        <xsl:variable name="result" select="dp:encrypt-string
         ('http://www.w3.org/2001/04/xmlenc#aes128-cbc', 
         'name:aes-128', $ssn)" />
    
        <dp:set-variable name="'var://context/mine/myvar2'" value="$result" />
    
        <output>
            <xsl:value-of select ="$result" />
        </output>
    
    </xsl:template>

    Once again, the output of this transform is not important. The setting of the variable value is what matters.

  25. Drag a Transform action onto the Processing Rule at the end.
  26. Double-click the icon.
  27. Under Use Document Processing Instructions, select Transform with processing control file, if specified as shown in Figure 18.
  28. The Input Language should be JSON, and the Transform Language should be Xquery.
  29. Click the Upload button under Processing Control file, and upload the use-dp-var.xq file.
  30. Set the Input to INPUT.
  31. Set the Output to OUTPUT.
  32. Click Done. The window closes.
    Figure 18. Transform with XQuery
    Transform with XQuery

    Here is the content of the use-dp-var.xq file:

    declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
    declare namespace dp = "http://www.datapower.com/extensions";
    declare option jsoniq-version "0.4.42";
    declare option output:method "json";
    
    let $ssn := .("Social-no")
    let $myvar := dp:variable("var://context/mine/myvar2")
    
    return
    
    jn:object(
     for $key in jn:keys(.)
     let $val := if ($key = "Social-no") then $myvar else .($key)
     return { $key : $val }
    )

    This script outputs the original message, substituting the encrypted field value for the original value.

  33. Click Apply Policy. If this completes the policy configuration desired, click Close Window to close the Processing Policy window. Then click Apply on the Gateway page.

    If you submit the sample document for encryption by this rule, the response resembles the following:

    {
      "State":"MA",
      "AccountID":"8458jf8757275234",
      "Social-no":"RynTyS5R0hTDDT7e/3OfK0ItyC4rCxZQr8a3D2yITck=",
      "Name":"Cartoon Studios"
    }

Element decryption using the shared secret Key

Follow these steps to use a shared secret key to decrypt elements of a JSON payload:

  1. Click New Rule.
  2. Change the name of the rule to SecureJSON_rule_ssdecrypt.
  3. Set the Rule Direction to Client to Server.
  4. Double-click the highlighted Match action icon.
  5. Click + to create a new Match.
  6. Enter dssn in the Name field as shown in Figure 19.
  7. Click the Matching Rule tab.
  8. Click Add.
  9. Type */dssn in the URL Match field.
  10. Click Apply. The window closes. The new rule is entered in the grid.
    Figure 19. Configure Matching Rule
    Configure Matching Rule
  11. Click Apply. The window closes.
  12. Click Done. The window closes. The blue Processing Policy pane is active again.
  13. Drag the Transform icon onto the processing line.
  14. Double-click the icon.
  15. Under Use Document Processing Instructions, select Transform with processing control file, if specified as shown in Figure 20.
  16. The Input Language should be JSON, and the Transform Language should be Xquery.
  17. Under Processing Control file, select the set-dp-var.xq file.
    Figure 20. Transform using XQuery
    Transform using XQuery
  18. Click Done. The window closes. Figure 21 shows the processing policy rule to this point.
    Figure 21. Processing Policy
    Processing Policy

    Here is the content of the set-dp-var.xq file:

    declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
    declare namespace dp = "http://www.datapower.com/extensions";
    declare option jsoniq-version "0.4.42";
    declare option output:method "json";
    
    let $ssn := .("Social-no")
    
    let $dono := dp:set-variable("var://context/mine/myvar1", $ssn)
    
    let $myvar := dp:variable("var://context/mine/myvar1")
    
    return
    
    jn:object(
     for $key in jn:keys(.)
     let $val := if ($key = "Social-no") then $myvar else .($key)
     return { $key : $val }
    )

    This script extracts the value of the Social-no JSON element from the submitted message, places it in a DataPower variable, and then uses that same variable to output the message again. The output of this transform is not important; it is the setting of the DataPower variable that is most important. This variable is used in the next step of the Processing Policy.

  19. Drag another Transform Action onto the Processing Rule.
  20. Double-click the icon.
  21. Under Use Document Processing Instructions, select Transform with XSLT stylesheet as shown in Figure 22.
  22. Upload the string-crypto-var-dec.xsl file.
  23. Type NULL in the Output context field.
    Figure 22. Configure XSLT Transform
    Configure XSLT Transform
  24. Click Done. The window closes.

    This stylesheet retrieves the value of the DataPower variable set in the previous step, decrypts it with the shared secred key, and places the result in a DataPower variable as shown below:

    <xsl:output method="xml"/>
    
    <xsl:template match="/">
        <xsl:variable name="ssn">
            <xsl:value-of select="dp:variable('var://context/mine/myvar1')" />
        </xsl:variable>
    
        <xsl:variable name="result" select="dp:decrypt-data
         ('http://www.w3.org/2001/04/xmlenc#aes128-cbc', 
         'name:aes-128', $ssn)" />
    
        <dp:set-variable name="'var://context/mine/myvar2'" value="$result" />
    
    
        <output>
            <xsl:value-of select ="$result" />
        </output>
    
    </xsl:template>

    Once again, the output of this transform is not important. The setting of the variable value is what matters.

  25. Drag a Transform action onto the Processing Rule at the end.
  26. Double-click the icon.
  27. Under Use Document Processing Instructions, select Transform with processing control file, if specified as shown in Figure 23.
  28. The Input Language should be JSON, and the Transform Language should be Xquery.
  29. Under Processing Control file, select the use-dp-var.xq file.
  30. Set the Input to INPUT.
  31. Set the Output to OUTPUT.
    Figure 23. Configure XQuery Transform
    Configure XQuery Transform
  32. Click Done. The window closes.

    Here is the content of the use-dp-var.xq file:

    declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
    declare namespace dp = "http://www.datapower.com/extensions";
    declare option jsoniq-version "0.4.42";
    declare option output:method "json";
    
    let $ssn := .("Social-no")
    let $myvar := dp:variable("var://context/mine/myvar2")
    
    return
    
    jn:object(
     for $key in jn:keys(.)
     let $val := if ($key = "Social-no") then $myvar else .($key)
     return { $key : $val }
    )

    This script outputs the original message, substituting the unencrypted field value for the encrypted value (Figure 24).

    Figure 24. Completed Decryption Policy
    Completed Decryption Policy
  33. Click Apply Policy. If this completes the policy configuration desired, click Close Window to close the Processing Policy window. Then click Apply on the Gateway page.

    If you submit the payload you encrypted with the shared secret key, the original JSON document is returned.

    {
      "Name":"Cartoon Studios",
      "AccountID":"8458jf8757275234",
      "Social-no":"123-45-6789",
      "State":"MA"
    }

Element encryption using asymmetrical keys

This method requires the use of Cryptographic Keys and Certificates. Follow the instructions in the Key and certificate pair section to create these key objects if you have not already done so.

  1. Click New Rule.
  2. Change the name of the rule to SecureJSON_rule_asencrypt.
  3. Set the Rule Direction to Client to Server.
  4. Double-click the highlighted Match action icon.
  5. Click + to create a new Match.
  6. Enter ssnain the Name field.
  7. Click the Matching Rule tab.
  8. Click Add.
  9. Type */ssna in the URL Match field.
  10. Click Apply. The window closes. The new rule is entered in the grid as shown in Figure 25.
    Figure 25. Configure Matching Rule
    Configure Matching Rule
  11. Click Apply. The window closes.
  12. Click Done. The window closes. The blue Processing Policy pane is active again.
  13. Drag a Transform action onto the Processing Rule at the end.
  14. Double-click the icon.
  15. Under Use Document Processing Instructions, select Transform with processing control file, if specified.
  16. The Input Language should be JSON, and the Transform Language should be Xquery.
  17. Click the Upload button under Processing Control file, and upload the extract-ssn-output.xq file.
  18. Click Done. The window closes.

    Here is the content of the extract-ssn-output.xq file:

    declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
    declare namespace dp = "http://www.datapower.com/extensions";
    declare option jsoniq-version "0.4.42";
    declare option output:method "xml";
    
      let $ssn := .("Social-no")
    
    return
    
    <output>
    {$ssn}
    </output>

    This script extracts the value of the Social-no element from the JSON request and wraps it in XML. In this case, the output of the script is important; this XML output is encrypted in the next action.

    Figure 26. Processing Policy
    Processing Polic
  19. Drag the Encrypt icon (Figure 26) onto the processing line.
  20. Double-click the icon. A new window opens.
  21. Set the Envelope Method to Standard XML Encryption.
  22. Set the Message Type to Raw XML Document.
  23. Use the Recipient certificate, Jason, as shown in Figure 27.
    Figure 27. Configure Encrypt Action
    Configure Encrypt Actio
  24. Click Done.
    Figure 28. Processing Policy
    Processing Policy

    In order to transmit the encrypted value across the network inside a JSON message, it is necessary to URL-encode the encrypted data block. The next action performs this task.

  25. Drag Transform Action (Figure 28) onto the Processing Rule.
  26. Double-click the icon.
  27. Under Use Document Processing Instructions, select Transform with XSLT stylesheet as shown in Figure 29.
  28. Upload the urlencode.xsl file.
  29. Set the Output to NULL.
    Figure 29. Configure XSLT Transform
    Configure XSLT Transform

    This stylesheet retrieves the Encrypted Data XML in the PIPE context, URL- encodes it for transport, and places the result in a DataPower variable. The output is not important.

    <xsl:output method="xml"/>
    
    
    <xsl:template match="/">
        <xsl:variable name="thisdoc">
            <dp:serialize select="." />
        </xsl:variable>
    
        <xsl:variable name="coded" select="dp:encode($thisdoc, 'url')" />
        <dp:set-variable name="'var://context/mine/encrypted'" value="$coded" />
    
        <output>
          <xsl:copy-of select="$coded" />
        </output>
    
    </xsl:template>
  30. Drag a Transform action onto the Processing Rule at the end.
  31. Double-click the icon.
  32. Under Use Document Processing Instructions, select Transform with processing control file, if specified.
  33. The Input Language should be JSON, and the Transform Language should be Xquery.
  34. Click Upload under Processing Control file, and upload the use-encrypted-var.xq file.
  35. Set the Input context to INPUT as shown in Figure 30.
  36. Set the Output context to OUTPUT.
    Figure 30. Configure Final XQuery Transform
    Configure Final XQuery Transform
  37. Click Done. The window closes. Figure 31 shows the completed processing policy rule.
    Figure 31. Completed Processing Rule
    Completed Processing Rule

    Here is the content of the use-encrypted-var.xq file:

    declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
    declare namespace dp = "http://www.datapower.com/extensions";
    declare option jsoniq-version "0.4.42";
    declare option output:method "json";
    
    let $ssn := .("Social-no")
    
    
    let $myvar := dp:variable("var://context/mine/encrypted")
    
    return
    
    jn:object(
     for $key in jn:keys(.)
     let $val := if ($key = "Social-no") then $myvar else .($key)
     return { $key : $val }
    )

    This script outputs the original message, substituting the encrypted data for the Social-no element.

  38. Click Apply Policy. If this completes the policy configuration desired, click Close Window to close the Processing Policy window. Then click Apply on the Gateway page.

    If you submit the sample JSON document to the Gateway using this rule, a partially encrypted document is returned as shown below:

    Click to see code listing

    {
      "State":"MA",
      "AccountID":"8458jf8757275234",
      "Social-no":"%3C%3Fxml+version%3D%221.0%22+encoding%3D%22UTF-8%22%3F%3E%0A%3Cxenc
      %3AEncryptedData+Type%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2F04%2Fxmlenc%23Element%22+xmlns%3Axenc
      %3D%22http%3A%2F%2Fwww.w3.org%2F2001%2F04%2Fxmlenc%23%22%3E%3Cxenc%3AEncryptionMethod+Algorithm
      %3D%22http%3A%2F%2Fwww.w3.org%2F2001%2F04%2Fxmlenc%23tripledes-cbc%22%2F%3E%3Cdsig%3AKeyInfo+xmlns
      %3Adsig%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2F09%2Fxmldsig%23%22%3E%3Cxenc%3AEncryptedKey+Recipient
      %3D%22name%3AJason%22%3E%3Cxenc%3AEncryptionMethod+Algorithm%3D%22http%3A%2F%2Fwww.w3.org%2F2001
      %2F04%2Fxmlenc%23rsa-1_5%22%2F%3E%3Cdsig%3AKeyInfo%3E%3Cdsig%3AKeyName%3EJason%3C%2Fdsig%3AKeyName
      %3E%3C%2Fdsig%3AKeyInfo%3E%3Cxenc%3ACipherData%3E%3Cxenc%3ACipherValue%3EYCbZxpgATnTDySkvoJPJEP
      %2BQfqo323mNnozEUxarFohagST06iY4R%2FuwFPsnQEAIVQbmQqxnvUJ3qA63DtBg4GXAEvAPdgyl1947qU8qtDJzTzLixEM7BE7H
      %2B7ITTDbPiUm6ZslhYe4hvhWYa441AqaA8tdMCL2e5MhcWliTK4Y%3D%3C%2Fxenc%3ACipherValue%3E%3C%2Fxenc
      %3ACipherData%3E%3C%2Fxenc%3AEncryptedKey%3E%3C%2Fdsig%3AKeyInfo%3E%3Cxenc%3ACipherData%3E%3Cxenc
      %3ACipherValue%3EhN7LmbrYWJuEM3hFQYjvXua2p%2FtjnQsgto6vQ%2F1HgzEd5SmjLlH5PgL%2FYCop1MSJPiWI9bO
      %2BYpl811Hi63gO9M3uf7H73%2F8CLTbKjQWkPvuTX0CkGP7LtHMgPGxLvHZxJpusGBN5f6A%3D%3C%2Fxenc%3ACipherValue
      %3E%3C%2Fxenc%3ACipherData%3E%3C%2Fxenc%3AEncryptedData%3E",
      "Name":"Cartoon Studios"
    }

Element decryption using asymmetrical keys

  1. Click New Rule.
  2. Change the name of the rule to SecureJSON_rule_asdecrypt.
  3. Set the Rule Direction to Client to Server.
  4. Double-click the highlighted Match action icon.
  5. Click + to create a new Match.
  6. Enter assn in the Name field.
  7. Click the Matching Rule tab.
  8. Click Add.
  9. Type */assn in the URL Match field.
  10. Click Apply. The window closes. The new rule is entered in the grid as shown in Figure 32.
    Figure 32. Configure Matching Rule
    Configure Matching Rule
  11. Click Apply. The window closes.
  12. Click Done. The window closes. The blue Processing Policy pane is active again.
  13. Drag a Transform action onto the Processing Rule at the end.
  14. Double-click the icon.
  15. Under Use Document Processing Instructions, select Transform with processing control file, if specified as shown in Figure 33.
  16. The Input Language should be JSON, and the Transform Language should be Xquery.
  17. Click the Upload button under Processing Control file, and upload the set-dpvar-encrypted.xq file.
    Figure 33. Configure XQuery Transform
    Configure XQuery Transform
  18. Click Done. The window closes. Figure 34 shows the processing policy rule up to this point.
    Figure 34. Processing Rule
    Processing Rule

    Here is the content of the set-dpvar-encrypted.xq file:

    declare namespace output = "http://www.w3.org/2010/xslt-xquery-serialization";
    declare namespace dp = "http://www.datapower.com/extensions";
    declare option jsoniq-version "0.4.42";
    declare option output:method "xml";
    
      let $ssn := .("Social-no")
    
    let $dono := dp:set-variable("var://context/mine/encrypted", $ssn)
    
    return
    
    <output>
    {$ssn}
    </output>

    In this case, the output is not important; setting the variable is important. It is used by the next action.

  19. Drag Transform action onto the Processing Rule.
  20. Double-click the icon.
  21. Under Use Document Processing Instructions, select Transform with XSLT stylesheet as shown in Figure 35.
  22. Upload the urldecode-var.xsl file.
  23. Type posted in the Output context field.
    Figure 35. Configure XSLT Transform
    Configure XSLT Transform
  24. Click Done. The window closes.

    The output of this stylesheet is important. I It is used by the Decrypt action that follows it.

    Here is the stylesheet:

    <xsl:output method="xml"/>
    
    
    <xsl:template match="/">
    
        <xsl:variable name="ssn">
           <xsl:value-of select="dp:variable('var://context/mine/encrypted')" />
        </xsl:variable>
    
        <xsl:variable name="decode">
           <xsl:value-of select="dp:decode($ssn, 'url')" />
        </xsl:variable>
    
        <xsl:copy-of select="dp:parse($decode)" />
    
    
    </xsl:template>
  25. Drag the Decrypt icon onto the processing line.
  26. Double-click the icon. A new window opens.
  27. Select posted from the possible Input contexts as shown in Figure 36.
  28. Set the Message Type to Entire Document.
  29. Use the Decrypt Key,Jason.
  30. Type outdata in the Output context field.
    Figure 36. Configure Decrypt Action
    Configure Decrypt Action
  31. Click Done.

    The decrypted data is now in the outdata context. The next action uses this input and places the data in a DataPower variable for use later on.

  32. Drag Transform action onto the Processing Rule.
  33. Double-click the icon.
  34. Select outdata from the list of possible Input contexts as shown in Figure 37.
  35. Under Use Document Processing Instructions, select Transform with XSLT stylesheet.
  36. Upload the make-decoded-var.xsl file.
  37. Enter relegate in the Output context.
    Figure 37. Configure XSLT Transform
    Configure XSLT Transform
  38. Click Done. The window closes. Figure 38 shows the processing policy rule up to this point.
    Figure 38. Processing Rule
    Processing Rule

    The output of this stylesheet is not important; setting the variable is important.

    Here is the stylesheet:

    <xsl:output method="text"/>
    
    <xsl:template match="/">
    
        <dp:set-variable name="'var://context/mine/decoded'" value="/output/text()" />
        <xsl:copy-of select="/output/text()" />
    </xsl:template>
  39. Drag a Transform action onto the Processing Rule at the end.
  40. Double-click the icon.
  41. Select INPUT from the list of possible Input contexts as shown in Figure 39.
  42. Under Use Document Processing Instructions, select Transform with processing control file, if specified.
  43. The Input Language should be JSON, and the Transform Language should be Xquery.
  44. Click the Upload button under Processing Control file, and upload the use-decoded-var.xq file.
  45. Select OUTPUT from the list of possible Output contexts.
    Figure 39. Configure XQuery Transform
    Configure XQuery Transform
  46. Click Done. The window closes.
  47. Click Apply Policy. If this completes the policy configuration desired, click Close Window to close the Processing Policy window. Then click Apply on the Gateway page.

    Here is the content of the use-decoded-var.xq file:

    let $ssn := .("Social-no")
    
    
    let $myvar := dp:variable("var://context/mine/decoded") cast as xs:string
    
    return
    
    jn:object(
     for $key in jn:keys(.)
     let $val := if ($key = "Social-no") then $myvar else .($key)
     return { $key : $val }
    )

    This file outputs the unencrypted message. If you submit the payload you encrypted with the asymmetrical keys to the Gateway, the original message is returned.

    {
              "Name":"Cartoon Studios",
              "AccountID":"8458jf8757275234",
              "Social-no":"123-45-6789",
              "State":"MA"
    }

Conclusion

The processing policies constructed in this article provided you with three different ways to secure a JSON payload transmitted in a REST-based architecture. This preserves the privacy of the payload regardless of the transport protocol. You learned how to encrypt both the entire payload or only select elements. You will probably only need to use one of the methods for a given use case. However, this provides you with a strategy or basis for creating just the security processing required by your scenario.

Figure 40 shows the Processing Policy with all of the rules described in this article.

Figure 40. Complete Processing Policy
Complete Processing Policy

Download

DescriptionNameSize
Code sampleJSON_code_sample_files.zip9KB

Resources

Learn

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere, Security
ArticleID=961174
ArticleTitle=Securing JSON payloads using WebSphere DataPower Appliances
publish-date=01292014