InCountry Bring Your Own Key (BYOK) Documentation

About document

The InCountry platform supports several types of encryption keys:

InCountry-managed encryption keys
Bring Your Own Key (BYOK)

These keys encrypt the regulated data when you write it to the InCountry platform and decrypt it when you read data from it.

This document outlines the flow and requirements for generating an encryption key with AWS KMS for further usage within the InCountry platform.

Data Encryption in the InCountry platform

InCountry services use encryption keys to encrypt data written to the InCountry platform and decrypt data that is read from it. By default, InCountry issues and manages all the encryption keys, but the platform also offers the Bring Your Own Key (BYOK) option. This option lets you provide the InCountry platform with access to your key management system, which the platform can request these encryption keys through API calls. This way, the customer fully manages the ownership and control over the encryption keys.

Currently, the Bring Your Own Key (BYOK) option supports AWS Key Management Service (AWS KMS) only. If you want to use different key management systems, please contact support@incountry.com and describe your use case.

Using Amazon KMS Data Keys in the InCountry platform

Data keys are encryption keys that can be used to encrypt data, including large amounts of data and other data encryption keys.

AWS provides an AWS Key Management System (AWS KMS), which issues KMS keys. They can be used to generate, encrypt, and decrypt data keys. AWS KMS does not store, manage, or track customer data keys or perform cryptographic operations with data keys. The data keys must be used and managed outside AWS KMS.

Creating an AWS KMS Data Key

To create a data key and return it in both plaintext and encrypted formats, run the GenerateDataKey command. AWS KMS uses your specific KMS key to generate a new data key. This command returns a plaintext copy of the data key and a copy of the data key encrypted by the KMS key.

To create a data key and return it in encrypted format only, run the GenerateDataKeyWithoutPlaintext command. This command returns only an encrypted data key. When you need to use the data key, you can request AWS KMS to decrypt it.

Encrypting and Decrypting Data with an AWS KMS Data Key in the InCountry Platform

AWS KMS itself cannot use the data key to encrypt data. But you can use the data keys outside of KMS, e.g., in cryptographic algorithms.

During the setup of the BYOK option on the InCountry Portal, you must provide an IAM user's encrypted data key and AWS credentials with specific KMS permissions.

During the setup of the BYOK in the InCountry platform, we will ask you to share only the encrypted version of the data key, and only the encrypted version will be stored on the InCountry side. The unencrypted data key will be obtained via AWS IAM credentials from AWS KMS and stored only in memory.

To encrypt/decrypt your data, the InCountry platform will use the Decrypt command on the AWS side, passing the provided AWS credentials and the encrypted data key to AWS KMS. AWS KMS will use your KMS key to decrypt the encrypted data key and then return the plaintext data key to the InCountry platform. The plaintext data key will encrypt/decrypt your data and remove it from memory as soon as possible.

The following diagram shows the data flow for requested encrypted data for the read operation on the InCountry platform.

When encrypted data is written to the InCountry platform, the flow is the following:

The customer’s application sends unencrypted data to the InCountry platform.
The InCountry platform retrieves the encrypted data key from the InCountry Internal Vault.
The InCountry platform uses IAM credentials to access AWS KMS and decrypt an encrypted data key.
The InCountry platform uses the unencrypted data key to encrypt the data received from the customer side.
The InCountry platform writes the encrypted data to the InCountry platform storage.

When encrypted data is read from the InCountry platform, the flow is the following:

The customer’s application requests data from the InCountry platform.
The InCountry platform retrieves the encrypted data key from the InCountry Internal Vault.
The InCountry platform uses IAM credentials to access AWS KMS and decrypt an encrypted data key.
The InCountry platform uses the unencrypted data key to decrypt the data stored in the InCountry platform storage.
The InCountry platform passes the decrypted data to the customer’s application.

For both data read and write scenarios, the decrypted data key is cached in memory for a short period to improve the performance of subsequent read/write transactions. Upon the timeout, the key expires and should be retrieved and decrypted again via AWS KMS.

Generating Amazon KMS Data Keys for the InCountry Platform

To successfully import the BYOK AWS KMS key to the InCountry platform, you need to:

Create a KMS key in AWS KMS
Generate an encrypted data key using the KMS key via AWS KMS
Create a new IAM policy with decrypt access to the created KMS key

Create a KMS Key via AWS KMS

During this step, a new AWS KMS key will be created that will be used for cryptographic operations on data keys that are used in the InCountry platform for encrypting and decrypting customer’s data.

Login into the AWS Console and select a preferred AWS region.
1. To ensure that latency from the InCountry Platform to AWS KMS endpoints will not be a contributing factor, we recommend creating the KMS key in the AWS region nearest the InCountry point-of-presence.
Navigate to Key Management Service.
To create a new KMS key, navigate to Customer Managed Keys and click Create key.
In Step 1, select Key type as Symmetric and Key usage as Encrypt and decrypt (in Advanced options, Key material origin should be selected as KMS and Regionality as Single-Region key).
In Step 2, add an Alias and Description for the created KMS key. Also, you can use any tags according to your AWS Tagging Policy (if it exists). InCountry recommends using meaningful names for the KMS key to prevent their accidental deletion.
Steps 3 (Define key administrative permissions) and 4 (Define key usage permissions) can be skipped for now. Access to the created KMS key will be defined in the next steps.
After reviewing all key properties in Step 5 Review, please create a KMS key by clicking Finish.
Your newly created KMS key will be shown in the Customer managed key section in the AWS KMS Console. Please allocate it, click on it, and copy the ARN value from the General configuration.

Generate an Encrypted Data Key via AWS KMS

During this step, a new data key will be created: its encrypted value will be stored on the InCountry side and used in the InCountry platform for encrypting and decrypting customer data.

To create an encryption data key, you need to have either access to the AWS IAM user with administrative privileges or access to an AWS IAM user with the following specific KMS permissions:
1. kms:GenerateDataKeyWithoutPlaintext
2. This user should be an internal customer user for creating data keys, and its credentials should not be shared with the InCountry platform in any way.
Make sure that you installed the AWS CLI on your machine and configured it by running the aws configure command and entering the credentials of the AWS IAM user with the kms:GenerateDataKeyWithoutPlaintext permission. Ensure the region name matches the AWS region code where the KMS key was created.
Generate a data key by running the following command, where the --key-id parameter should be your KMS key ARN from the previous step (e.g., arn:aws:kms:eu-central-1:111111111111:key/aaaaaaa-xxxx-yyyy-zzzz-bbbbbbbbbbb).
```
aws kms generate-data-key-without-plaintext --key-id <KMS\_KEY\_ARN> --key-spec AES\_256
```
Copy the encrypted data key from the CiphertextBlob key in the received JSON response and press q to exit.
```
{
    "CiphertextBlob": "ENCRYPTED\_DATA\_KEY",
    "KeyId": "KMS\_KEY\_ARN"
}
```

Create a New IAM Policy With Decrypt Access to the Created KMS Key

During this step, a new AWS IAM policy will be created with atomic access to decrypt using the created AWS KMS Key.

Login into the AWS Console.
Navigate to IAM (Identity and Access Management).
Navigate to Policies in the Access Management section and create a new custom IAM Policy (AWS does not have a pre-defined policy with the appropriate level of KMS access) by clicking Create policy.
In Step 1, we will define access permissions attached to this policy. First, select an AWS service as KMS.
One by one, enter the following actions to the Filter Actions input and check them to add to the policy:
1. Decrypt - permission to decrypt ciphertext that was encrypted under an AWS KMS key.
2. DescribeKey - permission to view detailed information about an AWS KMS key.
In the Resources section, select Specific and click Add ARNs.
In the pop-up window, limit access to a specific KMS key by entering KMS key ARN.
In Step 2, add a Policy Name and Description for the created IAM policy. InCountry recommends using meaningful names for IAM policies to prevent their accidental deletion. Review the permissions defined in this policy and click Create policy.

Create a New IAM User with a Previously Created IAM Policy

During this step, an IAM user will be created with the attached IAM policy, and new credentials will be issued for this IAM user.

Login into the AWS Console.
Navigate to IAM (Identity and Access Management).
Navigate to Users in the Access Management section and create a new IAM User by clicking Create user.
In Step 1, add a User name. InCountry recommends using meaningful names for IAM users to prevent their accidental deletion. Ensure the Provide user access to the AWS Management Console option is unchecked.
In Step 2, select Attach policies directly, search for created IAM policy, and check it.
In Step 3, review the user properties and click Create user.
After creation, find and click on the created user.
Navigate to the Security credentials section.
Find the Access keys section and click Create access key.
Select the Command Line Interface (CLI) option, check the confirmation checkbox, and click Next.
Enter the description tag value (optional) to distinguish the access keys from each other.
In the final step, copy and save the Access key and Secret access key.

Setting up a BYOK AWS KMS Key in the InCountry Platform

To perform the encryption and decryption in the InCountry platform with your key, you must register a new encryption key for a specific environment on the InCountry Portal.

Before proceeding with this, please ensure that you have all of the following items:

Encrypted Data Key
Access Key for IAM user
Secret Access Key for IAM user
KMS Key ARN
Region code

Once you have collected all the necessary items, please follow the instructions on registering an AWS KMS key on the InCountry Portal.

Feel free to contact the InCountry support team at support@incountry.com if you have any questions.

About document​

Data Encryption in the InCountry platform​

Using Amazon KMS Data Keys in the InCountry platform​

Creating an AWS KMS Data Key​

Encrypting and Decrypting Data with an AWS KMS Data Key in the InCountry Platform​

Generating Amazon KMS Data Keys for the InCountry Platform​

Create a KMS Key via AWS KMS​

Generate an Encrypted Data Key via AWS KMS​

Create a New IAM Policy With Decrypt Access to the Created KMS Key​

Create a New IAM User with a Previously Created IAM Policy​

Setting up a BYOK AWS KMS Key in the InCountry Platform​