Managing secret keys

The InCountry platform encrypts the data that you communicate to it through the REST API. Encryption of data records is based on secret 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: 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:

    • Plain - you can register your own Base64 encoded AES-256 keys on the InCountry Portal.

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

On the sidebar, select Secret Keys Management. The Secret Keys Management page opens, as follows:

The Secret Keys Management page

Here on the page, you can select a specific environment and country which secret keys you want to view. The page lists versions of the secret key that are stored in the key management service.

For each secret key, you can find the following information:

  • Name - name of the key.

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

  • Created - date and time when a secret key was created.

  • Created by - email of the user who generated a secret key.

  • Status - status of the secret key. It can be either Active or Deprecated.

list of secret keys and versions

Specifics of secret keys management

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

Please consider the following when generating a new secret key:

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

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

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

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

Existing limits

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

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

  2. You can generate up to 100 versions of customer-supplied secret keys. Do not register new versions of secret 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 secret key is generated.

Creating a new InCountry-managed secret key

  1. On the Secret Keys Management page, select the environment and country for which you want to generate a new secret key.

    select the environment and country

  2. Click Create new key.

    Use InCountry Key Management

  3. In the Generate new secret key form, select Use InCountry Key Management.

    Generate New Secret Key

  4. In the Create New Key form, specify the following information:

    • Secret Key Name - enter the secret key name.

    • Secret Key Expires in - select the expiry period for rotation of your secret keys on the InCountry platform. You can choose one of the following periods: 30 days, 60 days, 180 days, or 360 days.

  5. Click Generate.

  6. Enter the confirmation code and click Next.

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

note

Secret keys that were created earlier will have the default expiry period equal to 360 days.

Creating a new version of the InCountry-managed secret key

  1. Select the environment and the country for which you want to create a new version of the secret key.

  2. Click Create new version.

  3. In the Confirm action form, confirm the initiated operation by clicking Continue.

  4. Enter the confirmation code and click Next.

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

New version of InCountry-managed secret key created

Editing the InCountry-managed secret key

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

  2. Locate the secret key name.

  3. Click the cogwheel icon.

    Clicking cogwheel icon - edit secret key

  4. Modify settings of the secret key as required.

    Editing settings of InCountry-managed secret key

  5. Click Save.

  6. Enter the confirmation code and click Next.

Administering customer-supplied secret keys

The InCountry platform allows you to supply your own encryption keys either as a plain key (Base64 encoded AES-256) or as a AWS KMS generated key.

Creating a plain secret key

  1. On the Secret Keys Management page, select the environment and country for which you want to generate a new secret key.

  2. Click Create new key.

    select the environment and country

  3. In the Generate new secret key form, select Use Manual Key Management.

    Use Manual Key Management

  4. In the Generate new secret key form, specify the following information:

    • Secret key type - select Plain from the list.

    • Secret key name - enter the name of the secret key.

    • Plain encryption key - enter your encryption key (Base-64 encoded AES-256 key).

      Plain encryption key

  5. When complete, click Generate.

  6. Enter the confirmation code and click Confirm.

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.

Creating a new version of the plain secret key

  1. Select the environment and the country for which you want to create a new version of the secret key.

    Creating new version of plain key

  2. Click Create new version.

    Entering the plain key

  3. In the Create New Key form, enter the plain encryption key (base64-encoded).

  4. When complete, click Generate.

  5. In the Confirm action form, confirm the initiated operation by clicking Continue.

  6. Enter the confirmation code and click Next.

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

New version of the plain secret key

Editing the plain secret key

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

  2. Locate the secret key name.

  3. Click the cogwheel icon.

  4. Modify settings of the secret key as required.

  5. Click Save.

  6. Enter the confirmation code and click Next.

Creating a new AWS secret key

  1. On the Secret Keys Management page, select the environment and country for which you want to generate a new secret key.

    select the environment and country

  2. In the Generate new secret key form, select Use Manual Key Management.

    Use Manual Key Management

  3. In the Generate new secret key form, specify the following information:

    • Secret key type - select AWS from the list.

    • Secret Key name - enter the name of the secret key.

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

    • Encrypted key - enter the encrypted key.

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

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

    • IAM secret key - enter the IAM secret key.

      click Generate AWS key

  4. When complete, click Generate.

  5. Enter the confirmation code and click Next.

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.

← Managing usersManaging recommendation modules →