Encrypted data passporting

Data passporting is the mechanism to pass contextual data to the embedded application (see the data passporting). Encrypted data passporting is a way to pass sensitive contextual data via encryption.

What is encrypted data passporting?

The encrypted_passport property is an encoded string that contains an encrypted data_passport object. The string is generated by JWE compact encryption using the 128bit AES-GCM algorithm.

It is not necessary to pass all data via encrypted_passport. Data that does not require encryption can still be passed via the data_passport property.

In the application, both data_passport and encrypted_passport objects will be merged into the data_passport object. However, data from the encrypted_passport object will not be accessible by the client/browser. They are only accessible by the server. This makes it possible for the application to make API calls that need sensitive data or secrets.

Example use case

Imagine you are embedding a credit rating report service to your application. To streamline the process, you want to pre-fill certain user details so they don’t have to enter them manually. Therefore you intend to use the data_passport mechanism to pass the data to the application. However you do not want to expose sensitive cardholder data such as the the Primary Account Number to the internet.

Using encrypted_passport, the embedded service can recognise these values and use them without the risk of exposing sensitive data to the internet.

How encrypted data passporting works

Snippet generation and placeholder values

The snippet is generated the same way as with ordinary data passporting. The values that need to be encrypted are also defined in the variable configured as the data passport variable.

The snippet generated will automatically include the data_passport configuration that has been defined. The data_passport property will include the keys with placeholder value formatted as:

"{{YOUR-VALUE}}"

You will need to remove the keys of sensitive data you intend to pass to the application from the data_passport property and pass them in the encrypted_passport property instead.

Example generated snippet

mmob.init({
  deployer_id: "your-deployer-id",
  integration_id: "your-integration-id",
  location: "#app-container",
  owner_id: "your-owner-id",
  uid: "user-123456",
  data_passport: {
    first_name: "{{YOUR-VALUE}}",
    last_name: "{{YOUR-VALUE}}",
    card_number: "{{YOUR-VALUE}}"
  },
});

In this case we do not want the card_number to be passed unencrypted. Therefore we will need to remove it from the data_passport object and include it in encrypted_passport:

mmob.init({
  deployer_id: "your-deployer-id",
  integration_id: "your-integration-id",
  location: "#app-container",
  owner_id: "your-owner-id",
  uid: "user-123456",
  data_passport: {
    first_name: "{{YOUR-VALUE}}",
    last_name: "{{YOUR-VALUE}}"
  },
  encrypted_passport: "{{ENCRYPTED-VALUE}}"
});

Generating encrypted passport value

The passport value must be generated on the server, not on the client. The reason for this is to prevent either sensitive data or the encryption key from being exposed to the internet.

The data to be encrypted should be stringified as JSON and then encrypted with JWE using the following configuration:

• alg (key encryption algorithm): ECDH-ES+A128KW
• enc (data encryption algorithm): A128GCM

All other headers should not be set.

The following is an example of generating the encrypted value in javascript (node.js) using the jose library:

import * as jose from 'jose';

async function generateJWE (body, publicKey) {
	const parsedKey = JSON.parse(publicKey);
	const key = await jose.importJWK(parsedKey);

	const encryptedData = await new jose.CompactEncrypt(
		new TextEncoder().encode(JSON.stringify(body))
	)
	.setProtectedHeader({
		alg: 'ECDH-ES+A128KW',
		enc: 'A128GCM'
	})
	.encrypt(key);

	return encryptedData;
}