Skip to main content

Managing encryption keys

The InCountry platform encrypts the data that you communicate to it through the REST API. Encryption of data records is performed with encryption keys. Any use of InCountry REST API methods in the production mode without encryption of records is highly discouraged.

The InCountry platform provides two options for secret key management:

  • InCountry-managed encryption keys: You can manage encryption keys that are generated for you by the local KMS server on the InCountry Portal and stored in the key management service. Such keys support the key rotation and can be automatically rotated after a user-defined period of time.

  • Customer-supplied encryption keys (Manual): You can create and manage your own encryption keys that are further used for encryption of data passed through REST API. Such keys are managed as a part of the BYOK (Bring Your Own Key) approach provided by the InCountry platform. You can use two ways to supply these encryption keys to the InCountry platform:

    • AWS - you can register the AWS KMS service to generate encryption keys and supply them to the InCountry platform.

  1. Open a specific environment within where you want to create a new encryption key.

  2. Click the Encryption Keys block.

You will see the screen similar to the one displayed below:

Here on the page, you can select a country whose encryption keys you want to view. The page lists versions of the encryption key that are stored in the key management service of the InCountry Portal.

For each encryption key, you can find the general information, as follows:

  • Name - name of the encryption key.

  • Type - type of the encryption key (for example, InCountry-managed or AWS).

  • Rotation Period (days) - key rotation period in months. This is information is shown only for the InCountry-managed encryption keys.

  • Version - current version of the encryption key.

All the versions of the encryption key are listed in the table. For each version of the encryption key, the following information is displayed:

  • Version - current version of the encryption key.

  • Created - date when the encryption key version was created.

  • Status - status of the secret key. It can be either Active or Deprecated. Upon the generation of a new encryption key, the prior version becomes deprecated.

Specifics of secret keys management​

This section outlines the specifics of managing encryption keys on the InCountry platform.

Please consider the following when generating a new encryption key:

  1. The latest version of the encryption key is always used for the encryption of data records on the InCountry platform.

  2. The prior versions of the encryption key will be preserved for decryption of older data records to maintain compatibility.

  3. You can generate up to three versions for the same encryption key for each environment and for each country per day.

  4. Periodically re-encrypt your data records with the latest version of the encryption key to preserve their accessibility.

Existing limits​

Please consider the following limits when generating new versions of encryption keys:

  1. You can generate one version of an InCountry-managed or customer-supplied encryption key per day.

  2. You can generate up to 100 versions of customer-supplied encryption keys. Do not register new versions of encryption keys too often as you may run out of available versions.

Administering InCountry-managed secret keys​

When you use the InCountry-managed encryption keys, you should consider that key rotation policies are applied automatically. You can define the appropriate key rotation period upon expiry of which a new version of the encryption key is generated.

Creating a new InCountry-managed encryption key​

  1. Open the environment where you want to create a new encryption key.

  2. Click the Encryption Keys block.

  3. On the Encryption Keys page, select the country which you want to create an encryption key for.

  4. Click New Encryption Key.

  5. On the New Encryption Key page, define the parameters of a new encryption key:

    1. Key Type - select the encryption key type (InCountry Managed).

    2. Name - enter the encryption key name.

    3. Rotation Period - select the rotation period for this encryption key on the InCountry platform. You can choose one of the following periods: 30 days, 60 days, 180 days, or 360 days.

  6. Click Next.

  7. Enter the verification code and click Create.

A new encryption key appears on the list. It will be written automatically to the configuration of the REST API.

Rotating the InCountry-managed encryption key​

  1. Select the environment and the country where you want to create a new version of the encryption key.

  2. Click New Version.

  3. On the Rotate Encryption Key page, adjust the rotation period if needed.

  4. Click Next.

  5. Enter the verification code and click Rotate.

A new version of the encryption key appears on the list. The prior version of the encryption key will have the Deprecated label.

Editing the InCountry-managed encryption key​

  1. Select the environment and the country that are associated with the encryption key you want to edit.

  2. Click the cogwheel icon.

  3. Modify settings of the encryption key as required.

  4. Click Next.

  5. Enter the verification code and click Update.

Administering customer-supplied secret keys​

The InCountry platform allows you to supply your own encryption keys as a AWS KMS generated key.

Creating an AWS KMS encryption key​

  1. Open the environment where you want to create a new encryption key.

  2. Click the Encryption Keys block.

  3. On the Encryption Keys page, select the country which you want to create an encryption key for.

  4. Click New Encryption Key.

  5. On the New Encryption Key page, define the parameters of a new encryption key:

    1. Key Type - select the encryption key type (Manual: AWS).

    2. Name - enter the name of the encryption key.

    3. Region - specify the AWS region which is used for AWS KMS.

    4. Encrypted key - enter the encrypted key.

    5. Customer managed key (CMK) ARN - enter the customer manager key you created in AWS.

    6. IAM access key ID - enter the access key ID.

    7. IAM secret key - enter the IAM secret key.

  6. Click Next.

  7. Enter the verification code and click Create.

A new secret key appears on the list. Please contact the InCountry team to register this secret key in the configuration of your REST API.