InCountry Bring Your Own Key (BYOK) documentation

Table of сontents

• About Document
• Data encryption in InCountry platform
• Using Amazon KMS Data Keys
  • Creating a data key
  • Encrypting data with a data key
  • Decrypting data with a data key
  • InCountry Use of AWS KMS Data Keys
  • Generating an AWS KMS key
  • Provision of keys to the InCountry platform

About Document

The InCountry platform supports encryption keys. These keys are used to encrypt the regulated data when you write it to the InCountry platform and to decrypt when you read data from it. This document outlines the requirements for adding your encryption keys or generating an encryption key with Amazon KMS for their further usage within the InCountry platform.

Data encryption in InCountry platform

The InCountry platform provides all sorts of products for data localization and compliance, such as InCountry REST API and InCountry Border. They use encryption keys to encrypt data which is written to the InCountry platform and to decrypt data which is read from it. By default, InCountry issues, owns and manages all the encryption keys, but the company 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 ownership and control over the encryption keys are fully managed by the customer.

Using Amazon KMS Data Keys

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

Amazon provides AWS Key Management System (AWS KMS) which issues customer master keys (CMK's). 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 a data key

To create a data key, run the GenerateDataKey operation. AWS KMS uses the CMK that you specify to generate a data key. The operation returns a plaintext copy of the data key and a copy of the data key encrypted under the CMK. The following image shows this operation.

AWS KMS also provides the GenerateDataKeyWithoutPlaintext operation which returns only an encrypted data key. When you need to use the data key, you need to request AWS KMS to decrypt it.

Encrypting data with a data key

AWS KMS cannot use a data key to encrypt data. But you can use the data key outside of KMS, such as by using OpenSSL.

After using the plaintext data key to encrypt data, remove it from memory as soon as possible. You can safely store the encrypted data key with the encrypted data so it is available to decrypt the data.

Decrypting data with a data key

To decrypt your data, pass the encrypted data key to the Decrypt operation. AWS KMS uses your CMK to decrypt the data key and then it returns the plaintext data key. Use the plaintext data key to decrypt your data and then remove the plaintext data key from memory as soon as possible.

The following diagram shows how to use the Decrypt operation to decrypt an encrypted data key.

InCountry Use of AWS KMS Data Keys

If you want to use the BYOK option along with AWS KMS, you need to provide an encrypted data key as well as credentials through Identity Access Management to the InCountry platform. These credentials will be used to decrypt the data key at run time.  This decrypted data key is stored in memory only and is used to encrypt the regulated data that is saved to the InCountry platform or decrypt the regulated data that is retrieved from the platform. The following diagram show the data flows for requested encrypted data for the read operation.

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

1. The customer’s application sends unencrypted data to the InCountry Point-of-Presence (PoP) through REST API or Border.

2. The InCountry PoP retrieves the encrypted data key from the key vault.

3. The InCountry platform uses IAM credentials to AWS KMS to decrypt a data key which was retrieved from the key vault.

4. The InCountry PoP uses the unencrypted data key to encrypt the data received from the customer application.

5. The InCountry PoP writes the encrypted data to the InCountry platform.

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

1. The customer’s application requests data from the InCountry Point-of-Presence (PoP) through REST API or Border.

2. The InCountry PoP retrieves the encrypted data key from the key vault.

3. The InCountry platform uses IAM credentials to AWS KMS to decrypt the data key retrieved from the key vault.

4. The InCountry PoP uses the unencrypted data key to decrypt the data retrieved from the InCountry platform.

5. The InCountry PoP 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 of time to improve the performance of subsequent read/write transactions. Upon the timeout, the key expires and should be retrieved and decrypted via AWS KMS once again.

Generating an AWS KMS key

To generate an AWS KMS key please follow the instructions below.

Creating a Master Key

1. Open the AWS Console.

2. Navigate to Key Management Service

3. To create a new master key, click Create key.

   

4. Select the key type as Symmetric and key material origin as KMS.

   

5. Add an alias for the key (required, it will be used during encryption and data key generation) and a short description (what is this key for).

   

6. To find the Master Key ID (or arn), open the key details page.

   

note

The Master Key ID will be used to generate a data key.

Defining IAM Configuration

Creating IAM policy allowing to decrypt data keys

1. Navigate to IAM console.

   

2. Create a new Policy (AWS does not have a pre-defined policy with the appropriate level of KMS access).

   

3. Configure the policy, as follows:

   1. Service - select KMS.

   2. Actions - select Decrypt.

   3. Resources - select Specific.

      

4. Skip step #2 (tags creation).

5. Specify the policy name.

Creating an IAM user with the new policy

Once you have created the policy, you need to create a user for it.

1. In the AWS Console, navigate to Access management, then select Users.

2. Click Add user.

   

3. Enter the user name.

4. Set the Access type option as Programmatic access.

   

5. Select the newly created policy.

   

6. Save the credentials for the newly created user.

This user can be shared with InCountry, as this user has a very limited access to decrypt data only (decrypt encryption data keys you provide to us).

The user should be able to decrypt data only and not encrypt it.

Generating an Encryption Data Key

1. To create an encryption data key, you need to have an IAM user with the corresponding policy feature enabled (see the Defining IAM Configuration section. This should be an isolated user which InCountry should have NO access to.

   

2. Configure AWS CLI with the proper user credentials (the user should have access to the GenerateDataKeyWithoutPlaintext method).

   

3. Generate an encryption data key by using the following command (and using a master key id from KMS console).

   aws kms generate-data-key-without-plaintext --key-id <YOUR KEY ID starting with arn:aws:kms:...> --key-spec AES_256

4. In the received JSON response, copy the encrypted data key (in CyphertextBlob field).

   {
       "CiphertextBlob": <Your encrypted data key>,
       "KeyId": <KEY ID you provided>
   }

Provision of keys to the InCountry platform

To perform the data read and write operations in the InCountry platform with your own key, you need to register a secret key on InCountry Portal. Before doing this, please ensure that you have all of the following items:

• Encrypted Data Key

• IAM Access Key ID

• IAM Secret Access Key

• Master Key ID - identifies to AWS KMS which master key was used when creating the encrypted data key.

• Region - the AWS region used for AWS KMS.

Once you have collected all the required items, please check the following instructions on how to generate an AWS KMS key.

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