Ubiq Encryption in Apigee

The Ubiq Security Apigee library provides a convenient method of including the Ubiq Security Platform into your Apigee flows. Included are policies and code examples for setting up and performing encryption and decryption of data.

Configuration

Create a Key Value Map within your Apigee environment with the name Ubiq. For security, we recommend enabling the Encryption on your KVM. It will prevent your data from being accessed from outside your flows once added. We also recommend adding your ACCESS_KEY_ID, SECRET_SIGNING_KEY, and SECRET_CRYPTO_ACCESS_KEY as entries. This way you do not need to hardcode them in your flow, only pull them from your KVM.

Note: When accessing keys in an encrypted KVM, you must prefix your variable names with private. (eg. private.ACCESS_KEY_ID) or it will throw an error at runtime. For more information, view Apigee's Documentation on Key Value Map Operations

Apigee Dataset Flow

This is a flow for accessing Ubiq Dataset definitions. When you want to use the Ubiq library, add this to your flow BEFORE the call to the Java library.

Configuration

Shared Flow

Create a ZIP archive containing the sharedflowbundle folder. (If this it is named anything else, Apigee will consider it an empty bundle and return an error.) On Apigee, click to create a new Shared Flow and select Upload. Name the flow apropriately. (We recommend Ubiq Dataset Flow)

In Your Flow

Add a new Shared Flow policy. Select the flow you created in the previous step. You will need to add a new copy of the shared flow for each Dataset you wish to access. Update the Flow Callout XML to look like below for each dataset (for example, to access the definition needed to encrypt with the BIRTH_DATE dataset):

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="Get-BIRTH_DATE">
    <DisplayName>Get BIRTH_DATE</DisplayName>
    <Parameters>
        <Parameter name="ACCESS_KEY_ID">{private.ACCESS_KEY_ID}</Parameter>
        <Parameter name="SECRET_SIGNING_KEY">{private.SECRET_SIGNING_KEY}</Parameter>
        <Parameter name="dataset_name">BIRTH_DATE</Parameter>
        <Parameter name="dataset_ttl">30</Parameter>
        <Parameter name="save_decrypted_data_key">false</Parameter>
        <Parameter name="save_encrypted_data_key">false</Parameter>
    </Parameters>
    <SharedFlowBundle>Ubiq-Dataset-Flow</SharedFlowBundle>
</FlowCallout>

4 Key Parameters:

• ACCESS_KEY_ID - Your public access key (see your Ubiq Credentials).
• SECRET_SIGNING_KEY - Your secret signing key, used to sign requests to the Ubiq API (see your Ubiq Credentials).
• dataset_name - Name of the Dataset you are wanting to work with
• dataset_ttl - Minutes to hold a dataset definition before pulling a fresh copy. Prevents stale definitions in case of rotation. Defaults to 30 minutes.

Note: It is recommend to store your credentials in your encrypted "Ubiq" Apigee KVM rather than hardcoding it in your policies as plain text. If the KVM is encrypted, the variable will need to be prefixed with private.

Optional Parameters:

• save_decrypted_data_key: Retrieves data keys from the Ubiq platform but saves a cached copy of the decrypted data key in the KVM for fastest throughput.
• save_encrypted_data_keys: Retrieves data keys from the Ubiq platform and stored a symmetrically encrypted version in the KVM. This is significantly faster than storing an asymmetrically encrypted version of the data key in the KVM. This is only slightly slower than storing the decrypted version of the data key in the KVM.

Output

Output will be stored in two variables based on your dataset name:

• private.{dataset_name}.key
• private.{dataset_name}.definition.

(Example: private.BIRTH_DATE.key) These will be private to prevent them from being shown when the flow is viewed in Apigee's trace functionality.

Apigee Sample Application

Java Callout

This is the piece that responds to the Apigee workflow and calls the Ubiq libraries to encrypt the data. This repo contains all the files necessary to run the sample application with the exception of editing the setenv.sh file referenced below.

Requirement

Apigee uses Java 1.8 for the execution environment so all programs / libraries need to be developed for the the Java 1.8 environment. Apigee has restrictions on the libraries that can be used / referenced by the callout application. See the Apigee documentation for additional information. There are also restrictions regarding the size of the jars that can be uploaded with the deploy script.

In addition to having an account within Apigee you will need to edit the setenv.sh for your environment.

Program Flow

Apigee callout programs require a class which implements Execution and has the execute method. The execute method accepts both a MessageContext and ExecutionContext. The callout also expects certain variables to be set in the KVM in order to interact with the Ubiq Encryption libraries.

Required Variables preset in the KVM

The following variables must be set in the Apigee KVM. Because these are stored encrypted in the Apigee KVM, internally, they are accessed by prefixing the name 'private.'

 ACCESS_KEY_ID
 SECRET_CRYPTO_ACCESS_KEY

Within the 'execute' method, the following lines retrieve the values from the KVM

  ACCESS_KEY_ID = getVar(messageContext, "private.ACCESS_KEY_ID");
  SECRET_CRYPTO_ACCESS_KEY = getVar(messageContext, "private.SECRET_CRYPTO_ACCESS_KEY");

Mapping dataset name to the json fields to encrypt

The apiproxy/policies/ubiq-poc.xml contains the DatasetsMappings which contains JSON representation of the mappings between dataset name and the field to encrypt

The example below shows that the json path containing the field birthDate should be encrypted using the BIRTH_DATE dataset. Similarly, any field found with the name ssn should be encrypted using the SSN dataset.

[
   { "dataset" : "BIRTH_DATE", "json_path" : "$..birthDate"},
   { "dataset" : "SSN", "json_path" : "$..ssn"}
]

The Dataset mapping is read and processed into a hashmap containing the DATASET name as the key and the json_path as the value.

Usage Reporting

The apiproxy/policies/ubiq-poc.xml contains setting to control the granular level of usage reporting. All encrypt / decrypt operations for a dataset will be summed together within the granular level. For example, When set to HOURS, a single count will be reported for all encrypt operations the same dataset operation within the same hour, XX:00:00 - XX:59:59.9999

        <Property name="usage_timestamp_reporting_granularity">HOURS</Property>

Valid values are shown below with NANOS being the default

• DAYS
• HALF_DAYS
• HOURS
• MINUTES
• SECONDS
• MILLIS
• NANOS

Encryption flow

The data to encrypt is passed into the Java callout using the Message context. The json is parsed and then the program iterates over the dataset mappings hashmap to encrypt all of the values found based on the json path and dataset.

The resulting json is then formatted and returns in the MessageContext.

apiproxy policies and proxies

The policies directory contains the following files

The credentials.xml contains the setup of retrieving variables from the encrypted KVM.

The RetrieveBirthday.xml is an example of the setup required by the shared flow in order to retrieve the BIRTH_DATE dataset from the Ubiq platform or read the values that are cached in the Apigee KVM. See the description of the Shared Flow

The RetrieveSSN.xml is an example of the setup required by the shared flow in order to retrieve the BIRTH_DATE dataset from the Ubiq platform or read the values that are cached in the Apigee KVM.

As described above, the ubiq-poc.xml contains the mappings between dataset name and the corresponding json path to the fields that require encryption.

The proxy directory contains the following file

The default.xml contains the processing steps. In this case, the setup of the credentials, checking for the BIRTH_DATE dataset, checking for the SSN dataset, and then invoking the ubiq-poc.

The resources/java directory

This directory contains the JAR files that are deployed to Apigee. The necessary Ubiq libraries are already included in this directory as well as other libraries required by the sample application. Some dependencies are automatically supplied by the Apigee environment and are not included in this directory to prevent conflicts. Apigee has a limitation to the size of the resources/java directory. See the Apigee documentation for additional information.

Compiling

Requires a Java 1.8 environment.

Uses maven to compile and package the application.

The deployment scripts deploy.sh require Python 2

 # Install library dependencies into the local maven cache.
$ ./buildsetup.sh


$ cd callout

# Only required if modifying the sample application.  Otherwise you can skip to the deploy and invoke scripts
$ mvn compile package

$ cd ..

# Requires python 2 for the next two steps
$ ./deploy.sh

$ ./invoke.sh