DSM Accelerator Webservice with Snowflake

1.0 Introduction

This article explains the procedures to integrate the Fortanix-Data-Security-Manager (DSM) Accelerator Webservice with Snowflake.

2.0 Integration Steps

This section lists the steps for integrating the Fortanix DSM Accelerator Webservice with Snowflake external tokenization.

2.1 Data Format

The data format for both input and output data regarding tokenization and detokenization is uniform. The data payload sent to the Fortanix DSM Accelerator Webservice for tokenization or detokenization must follow the following structure:

Data Format for Tokenization:

{
  // Comma-delimited list of Key Names
  "keys": String,
  // Array of heterogeneous arrays
  "data": [
    // Heterogeneous array which starts with an integer followed by a series of strings
    [int, String, String, ..], 
    ..
  ]
}

Data Format for Detokenization:

{
  // Comma-delimited list of Key IDs
  "keys": String,
  // Array of heterogeneous arrays
  "data": [
    // Heterogeneous array which starts with an integer followed by a series of strings
    [int, String, String, ..], 
    ..
  ]
}

Following the tokenization process, the output data will maintain a structure closely resembling that of the input, except for the keys field:

{
  // Array of heterogeneous arrays
  "data": [
    // Heterogeneous array which starts with an integer followed by a series of strings
    [int, String, String, ..], 
    ..
  ]
}

Ensure to note that the order of the data rows remains unchanged.

2.2 Call the API

To initiate the APIs, a POST HTTP request must be made to the respective endpoints:

• For tokenization: <DSMA-WS-URL>/crypto/v1/snowflake_tokenize

• For detokenization: <DSMA-WS-URL>/crypto/v1/snowflake_detokenize

For example, consider the following input provided to the tokenization endpoint:

{
    "keys": "keyname1, keyname2",
    "data": [ [ 1, "john@gmail.com", "374245455400126" ], [ 5, "harry@gmail.com", "378282246310005" ] ]
}

This input will reflect the following output:

{
    "data": [ [ 1, [ "uz87@lAUlp.KPg", "355347704783659" ] ], [ 5, [ "Ni0BE@w89JR.s9b", "186322926918719" ] ] ]
}

For example, consider the following input provided to the detokenization endpoint:

{
    "keys": "e9d51a2f-0d7a-42c0-9c51-24107f957464,822000bc-4f12-4007-b2d0-226726d78f55",
    "data": [ [ 1, [ "uz87@lAUlp.KPg", "355347704783659" ] ], [ 5, [ "Ni0BE@w89JR.s9b", "186322926918719" ] ] ]
}

This input will reflect the following output:

{
    "data": [ [ 1, "john@gmail.com", "374245455400126" ], [ 5, "harry@gmail.com", "378282246310005" ] ]
}

2.3 Create and Test AWS API Gateway

To integrate AWS API Gateway with Lambda which is deployed with Fortanix DSM Accelerator Webservice, create a REST API with public or private endpoints for /tokenize and /detokenize.

2.4 Configure an Integration Request

For each resource method, set up an integration request with the following parameters:

• Integration type: HTTP

• Method type: POST

• Endpoint URL: Point this to your Fortanix DSM Accelerator Function URL.

  For example, if Fortanix DSM Accelerator is deployed on AWS Lambda:

  • For tokenization: https://<url-id>.lambda-url.<region>.on.aws/crypto/v1/snowflake_tokenize

  • For detokenization: https://<url-id>.lambda-url.<region>.on.aws/crypto/v1/snowflake_detokenize

  For more information on setting up the Fortanix DSM Accelerator on AWS Lambda, refer to DSM Accelerator Webservice Deployment on AWS Lambda.

• Content handling: Passthrough

• HTTP Headers: Add an “Authorization” header and leave the value empty, as Snowflake sends it through an External Function custom header.

  

2.5 Map the Template Configuration

2.5.1 Tokenization

Click Add mapping template and configure as follows:

• Content-Type: application/json

• Request body passthrough: Never

• Template:

  #set($inputRoot = $input.path('$'))
  #set($apikey = "Basic $input.params('sf-custom-api-key')")
  #set($context.requestOverride.header.Authorization = $apikey)
  #set($context.requestOverride.header.sf-custom-api-key = "")
  #set($context.requestOverride.header.sf-custom-key-names = "")
  {
  "keys":"$input.params('sf-custom-key-names')",
  "data": $input.json('$.data')
  }

2.5.2 Detokenization

Click Add mapping template and configure as follows:

• Content-Type: application/json

• Request body passthrough: Never

• Template:

  #set($inputRoot = $input.path('$'))
  #set($apikey = "Basic $input.params('sf-custom-api-key')")
  #set($context.requestOverride.header.Authorization = $apikey)
  #set($context.requestOverride.header.sf-custom-api-key = "")
  #set($context.requestOverride.header.sf-custom-key-ids = "")
  {
  "keys":"$input.params('sf-custom-key-ids')",
  "data": $input.json('$.data')
  }

Test the AWS API Gateway with the following input:

• Resource: /tokenize

• Query String: None or leave blank.

• Headers:

  Accept: application/json
  sf-custom-api-key: <<FORTANIX_DSM_API_KEY>>
  sf-custom-key-names: <<KEY_NAME_1,KEY_NAME_2,KEY_NAME_3,KEY_NAME_X,,,>>

• Request Body:

  {    "data": [
          [
              1,
              "174008549993007"
          ]
      ]}

  The highlighted box in the figure refers to the key name as Credit_Card_Token is used for tokenization.

  

• Output:

  • In the response body, you can observe the tokenization output:

    

    The highlighted box in the following figure refers to the key ID as <ac00221c-8b04-4eed-8191-060bafcda40d> is used for detokenization.

    

  • In the response body, you can observe the detokenization output which matches the original data.

    

2.7 Finalize the API Gateway Integration

Perform the following steps to complete the API Gateway integration:

1. Create an AWS IAM role that Snowflake will assume for execution.

2. Deploy the proxy service on a demo stage and note the public or private URI:

   https://<<XYZ.execute-api.us-east-2>>.amazonaws.com/<<DEMO_STAGE>>/

For setting up the Snowflake API integration and external functions, refer to Fortanix DSM with Snowflake for Tokenization.