Table of сontents
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.
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:
The customer’s application sends unencrypted data to the InCountry Point-of-Presence (PoP) through REST API or Border.
The InCountry PoP retrieves the encrypted data key from the key vault.
The InCountry platform uses IAM credentials to AWS KMS to decrypt a data key which was retrieved from the key vault.
The InCountry PoP uses the unencrypted data key to encrypt the data received from the customer application.
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:
The customer’s application requests data from the InCountry Point-of-Presence (PoP) through REST API or Border.
The InCountry PoP retrieves the encrypted data key from the key vault.
The InCountry platform uses IAM credentials to AWS KMS to decrypt the data key retrieved from the key vault.
The InCountry PoP uses the unencrypted data key to decrypt the data retrieved from the InCountry platform.
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
Open the AWS Console.
Navigate to Key Management Service
To create a new master key, click Create key.
Select the key type as
Symmetricand key material origin as
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).
To find the Master Key ID (or
arn), open the key details page.
The Master Key ID will be used to generate a data key.
Defining IAM Configuration
Creating IAM policy allowing to decrypt data keys
Navigate to IAM console.
Create a new Policy (AWS does not have a pre-defined policy with the appropriate level of KMS access).
Configure the policy, as follows:
Service - select
Actions - select
Resources - select
Skip step #2 (tags creation).
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.
In the AWS Console, navigate to Access management, then select Users.
Click Add user.
Enter the user name.
Set the Access type option as
Select the newly created policy.
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
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.
Configure AWS CLI with the proper user credentials (the user should have access to the
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
In the received JSON response, copy the encrypted data key (in
"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 email@example.com, if you have any questions.