1. Fortanix
  2. Fortanix Data Security Manager (DSM)
  3. Integration / Use-case
  4. Transparent Encryption Proxy

Using Data Security Manager with Transparent Encryption Proxy (TEP) - Beta

Last Updated: 

1.0 Introduction

This article describes how to configure a Transparent Encryption Proxy (TEP) in Fortanix Data Security Manager (DSM). It also explains the TEP user onboarding workflow. ​TEP is a local API request/response encryption proxy that helps users to encrypt browser inputs before sending them to the upstream and decrypt the upstream responses before sending them back to the browser.

2.0 Definitions

  • Content Type: The type of requests such as JSON and Form.
  • Request: Actual payload sent to TEP over TLS.
  • Schema: Specific schema of request composing of data types that need to be encrypted.
  • Encryption/Tokenization: Only the fields inside specific payloads configured in the schema are encrypted/tokenized.

3.0 User On-Boarding Flow

3.1 Add a new TEP Instance in Fortanix DSM

You can create a TEP integration in Fortanix DSM and set up the TEP instance to connect to the Fortanix DSM TEP app and encrypt/decrypt/tokenize/detokenize certain fields in the request/response payload.

The following modules are involved in providing this functionality:

  1. Fortanix DSM TEP app, which provides Fortanix DSM crypto operation access.
  2. TEP instance, which the proxy module client uses to check payload and communicate with Fortanix DSM for crypto operations.
  3. The client program communicates with the client backend.
  4. Client backend.

TEP-functionality.png
Figure 1: TEP functionality modules

To access the TEP Wizard in Fortanix DSM:

  1. Sign up at https://smartkey.io/.
  2. Log in to the Fortanix DSM UI.
  3. Click the Integrations tab in the left panel.
  4. On the Integrations page, click ADD TEP INSTANCE on the TEP wizard which will allow you to configure TEP.

    TEP-IntegTab.png
    Figure 2: Add TEP instance
  5. On the TEP wizard, enter an Instance name.
  6. Select the group you want the instance to belong to.
  7. Click Add Schema to manually configure the data types in the request payload that need to be encrypted/tokenized.
  8. In the Configure Schema section:
    1. Select the Upstream Method to add upstream which is the complete URL with host and path of the format: https://<host>/<path>. For example: https://test.com/get/keys
    2. Select the Field Info and provide the path of certain fields in a given payload. The supported payloads are JSON and URL encoded forms.See the example below:
      For JSON:
      items.*.data.value: matches all fields called value, inside data, which belongs to an array inside the key items. * is a wildcard.
      For Form:
      name matches the field with a key called name. JSON inside the Form will be supported in future DSM releases.
    3. Click MAP DSM KEY and select a key from the group selected in Step 6 to map the key to the field and select the MODE.
      • You can map the same key/token objects for all the fields or
      • You can map different key/token objects for different fields
  9. Click ADD ANOTHER FIELD to add additional fields if required.
  10. Click ADD ANOTHER DATA TYPE to add additional data types if required.
  11. Click SAVE INSTANCE to save the TEP instance.

    TEP_ConfigSchema.png
    Figure 3: Configure schema
    NOTE
    After you have created the TEP app you cannot modify it. This is because when a certain field is mapped to a key and you change the key, all the data in that field will become unusable. Modifying the app will be supported in a future DSM release.

After you have saved the TEP instance, the following steps will happen automatically:

  1. A new app will be created of type TEP.
    1. This app will have an API key that you can use to communicate with Fortanix DSM and perform the crypto operations.

      TEP-Sessions.png
      Figure 4: TEP sessions workflow

3.1.1 Management of TEP Instance

  • As part of the TEP instance configuration, only one app of the type TEP is created automatically.
  • If you want to deploy additional TEP/Proxy instances, you should create an equal number of extra TEP apps in the same TEP group in case you want to use the same schema and data protection configuration.
  • Optionally, you can create additional TEP instances in Fortanix DSM if you want to create a whole new set of schema mappings and data protection configurations.
  • All the TEP instances are listed on the main page.
  • You can edit the TEP instance’s configuration or delete the TEP instance. The actual TEP/Proxy instance needs to be re-booted for the updated TEP configuration to become active. In case of deletion, the TEP app is deleted.

4.0 TEP Deployment

The purpose of this section is to describe the steps required to set up and run the Transcription Encryption Policy (TEP) on Fortanix Data Security Manager (DSM).

4.1 Prerequisites for TEP Setup

TEP is an API request/response encryption proxy written in rust.

The following are requirements to make it work:

  • To allow modifying the payload, a custom domain must be used to wrap the actual upstream. For example, if the user wants to set up TEP for servicenow.com, then servicenow.test.com together with reverse proxy should be prepared. In this case, the latter URL will be used in the browser, and all the requests are sent to servicenow.test.com first, which allows payload modification.
  • Forward the interesting packages to TEP instance(s) in the reverse proxy with PROXY_TARGET set in the header which indicates the actual upstream.
  • The TEP.toml configuration file that should be mapped to /etc/tep/TEP.toml. This file looks as follows: 
    [server]
# Port Number the proxy server will listen to
port = 8001
# Url the (un)modified HTTP package will be sent to
target_url = ""
# Path of the server certificate, der format
cert_path = ""
# Path of the server private Key, pem format
key_path = ""

# use it in case you want TEP help you replace url in
# response from certain path, you need to pass the package
# to TEP.
[url_replacement]
# the upstream url given in Proxy-Targe header will be
# replaced by the below url
tep_url = ""
path_list = []
# in case we need to talk to server hosted with self-signed CA.
# comment out cert_path if you don't use it.
[client]
# cert_path = ""
  • FORTANIX_API_ENDPOINT and FORTANIX_API_KEY (TEP app’s API key). A TEP Integration should be created in the FORTANIX_API_ENDPOINT which provides FORTANIX_API_KEY. Refer to Section 3.1 for steps to create a TEP instance. These two environment variables should be provided when starting the TEP.
  • Certificate and private key to run TEP in Transport Layer Security (TLS). The location and format of the files are described in the configuration file above.

5.0 Start the Docker

Fortanix releases TEP as a docker image. You can download the image from the Fortanix DSM Downloads page.

5.1 Start the Services

To start the services:

  1. Install the TEP docker image from the tep.tar file. 
    # load the tep docker image
docker load -i tep.tar
# you should find fortanix/tep:1.0 when
docker image ls
# go to the folder of setup.zip and unzip it
docker compse up
  2. Start the docker. 
    sudo docker run -t -d \
-v ../certs_and_cfg/TEP.toml:/etc/tep/TEP.toml \
-v ../certs_and_cfg/:/etc/tep/userfile/ \
-p 8001:8001 \
-e FORTANIX_API_ENDPOINT="https://www.sit.smartkey.io/" \
-e FORTANIX_API_KEY="xxxx" \
fortanix/tep:1.0
    NOTE
    Before starting it, make sure the TEP.toml file is created. The certificate and keys are in the folder which will be mounted to /etc/tep/userfile/*. In this case, the cert_path and key_path in the configuration file will begin with /etc/tep/userfile.

 

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful