Customer KMS keys

Create cross-account AWS KMS keys for Kosli Dedicated and share them with Kosli for data-at-rest encryption.

Kosli Dedicated is a single-tenant Kosli instance, hosted on infrastructure dedicated to your organization. On a Dedicated instance you provide Kosli with the AWS KMS keys that encrypt all data at rest.

Kosli hosts your data across two AWS regions — a primary and a secondary — so you provide a key in each region. This page walks through creating those keys in the AWS Console (with an equivalent Terraform example) and sharing their ARNs with Kosli.

A member of the Kosli Customer Success team will give you:

• The primary and secondary AWS regions your instance uses.
• The Kosli AWS account ID (<<kosli-account-id>>) to grant access to in the key policy.

Prerequisites

• An AWS account you will use to own the KMS keys.
• Permissions in that account to create and manage KMS keys.
• The primary/secondary regions and the Kosli account ID (<<kosli-account-id>>) from a member of the Kosli Customer Success team.

Choose the key shape

AWS does not permit multi-region KMS keys whose key material lives in a custom key store.

• If your key material can live in KMS (generated or imported), create one multi-region key in the primary region and replicate it into the secondary region. This is the path described below.
• If your policy requires an AWS CloudHSM key store or an external key store for key material, create two single-region keys — one in each region. See Single-region keys for the differences.

Most of the steps are identical for both shapes.

The instructions use the AWS Console. If your organization uses AWS CDK or another IaC tool, the Terraform example gives enough detail to translate.

Create the primary key

1. Sign in to the AWS account that will own the keys and open the AWS KMS service.

2. KMS is a regional service. Switch the console to the primary Kosli region.

   

3. In the left-hand menu, select Customer-managed keys.

   

4. Click Create key in the top right to start the wizard.

Step 1 — Configure the key

• Key type: Symmetric
• Key usage: Encrypt and decrypt
• Expand Advanced options and, under Regionality, select Multi-region key.

Selecting Multi-region key rules out a custom key store as the key material origin. You can still choose KMS or External (Import Key material). If you need CloudHSM or an external key store, see Single-region keys.

Click Next.

Step 2 — Add labels

• Alias: use whatever labelling strategy your organization prefers, for example alias/kosli-dedicated-cross-account-key.
• Optionally add a description and tags to help your team.

Click Next.

Step 3 — Define key administrators

The key is not used from inside your AWS account, so there is usually no reason to add key administrators.

To protect against accidental deletion, untick Allow key administrators to delete this key under Key deletion.

The console ticks this by default — untick it before clicking Next.

Click Next.

Step 4 — Define key usage permissions

The key policy is managed as JSON on the next screen, so leave the usage permissions on this page unselected. Do not add an “Other AWS account” here either — cross-account access is granted via the JSON policy.

Click Next.

Step 5 — Edit the key policy

The console loads a default policy that grants access to your account root. Click Edit, then click Add new statement and add a second statement to the Statement array with the following content. A member of the Kosli Customer Success team will give you the value for <<kosli-account-id>>.

{
    "Sid": "Allow Kosli-Dedicated to use this KMS key",
    "Effect": "Allow",
    "Principal": {
        "AWS": [
            "arn:aws:iam::<<kosli-account-id>>:root"
        ]
    },
    "Action": [
        "kms:CreateGrant",
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
    ],
    "Resource": "*"
}

Make sure you add a comma between the existing statement object and this new one.

Click Preview to format and validate the JSON. The preview shows both statements — one for your AWS account root, one for the Kosli-Dedicated account.

Click Next.

For background on key policy syntax, see the AWS key policies documentation.

Step 6 — Review and finish

Confirm the settings match:

Field	Value
Key type	Symmetric
Key spec	SYMMETRIC_DEFAULT
Key usage	Encrypt and decrypt

If anything needs changing, click Edit for that section. Otherwise click Finish to create the key. You are returned to the customer-managed keys list with the new key at the top.

Replicate the key to the secondary region

1. Click the new key’s alias to open its details.

2. Select the Regionality tab. The Primary key panel shows that the key has no replicas yet.

   

3. Click Create new replica keys.

4. In the region dropdown (which excludes the primary region), tick the Kosli secondary region and click Next.

   

5. The Add labels screen is pre-populated from the primary key. Change if your organization requires it, otherwise click Next.

6. The console pre-populates the replica’s policy from the primary key — no changes needed. Click Next.

7. Review the Confirmation message, tick the acknowledgement box, and click Create new replica keys.

The primary key’s details page reloads with the replica listed under Related multi-region keys.

Share the key ARNs with Kosli

Kosli uses the primary and replica keys to encrypt data. Send both ARNs to a member of the Kosli Customer Success team:

• The primary key ARN — from the General configuration panel of the primary key’s details page.
• The replica key ARN — from the Related multi-region keys panel on the same page, or from the replica key’s own details page in the secondary region.

For a multi-region key the two ARNs are identical except for the region segment.

A key ARN is an identifier, not a secret: only the AWS account named in the key policy can use the key, so the ARNs can be shared over email.

Single-region keys

If your organization requires a CloudHSM key store (or an external key store) for the key material, create two single-region keys instead of one replicated multi-region key.

The steps to create the primary key are the same as above, with two differences:

• Do not tick Multi-region key under Regionality.
• Under Key material origin, select your CloudHSM key store (or external key store) rather than KMS.

Once the primary key exists, switch the console to the secondary Kosli region and repeat the process. Include a reference to the primary key’s ARN or alias in the secondary key’s Description so the pairing is obvious later.

Share both ARNs with a member of the Kosli Customer Success team. Unlike a multi-region key, the two single-region ARNs differ beyond just the region segment.

Terraform example

The following is the minimum Terraform needed to create the multi-region key and its replica for Kosli Dedicated. Set primary_aws_region, secondary_aws_region, and kosli_dedicated_account_id for your instance.

This example uses the top-level region argument on aws_kms_key, aws_kms_alias, and aws_kms_replica_key, which requires AWS provider v6.0 or later. On earlier versions, use aliased provider blocks instead.

variable "primary_aws_region" {
  type        = string
  description = "Primary AWS region for your Kosli Dedicated instance"
}

variable "secondary_aws_region" {
  type        = string
  description = "Secondary AWS region for your Kosli Dedicated instance"
}

variable "kosli_dedicated_account_id" {
  type        = string
  description = "Kosli AWS account ID, supplied by the Kosli Customer Success team"
}

data "aws_caller_identity" "current" {}

resource "aws_kms_key" "primary" {
  description = "Multi-region key for Kosli-Dedicated"

  deletion_window_in_days = 30

  multi_region = true
  region       = var.primary_aws_region

  key_usage                = "ENCRYPT_DECRYPT"
  customer_master_key_spec = "SYMMETRIC_DEFAULT"

  policy = jsonencode({
    Version = "2012-10-17"
    Id      = "kosli-dedicated-kms"
    Statement = [
      {
        Sid    = "Enable IAM User Permissions"
        Effect = "Allow"
        Principal = {
          AWS = "arn:aws:iam::${data.aws_caller_identity.current.account_id}:root"
        }
        Action   = "kms:*"
        Resource = "*"
      },
      {
        Sid    = "Allow Kosli-Dedicated to use this KMS key"
        Effect = "Allow"
        Principal = {
          AWS = "arn:aws:iam::${var.kosli_dedicated_account_id}:root"
        }
        Action = [
          "kms:CreateGrant",
          "kms:Encrypt",
          "kms:Decrypt",
          "kms:ReEncrypt*",
          "kms:GenerateDataKey*",
          "kms:DescribeKey"
        ]
        Resource = "*"
      }
    ]
  })
}

resource "aws_kms_alias" "primary_alias" {
  region = var.primary_aws_region

  name          = "alias/kosli-dedicated-cross-account-key"
  target_key_id = aws_kms_key.primary.key_id
}

resource "aws_kms_replica_key" "replica" {
  region = var.secondary_aws_region

  description             = "Multi-region replica key"
  deletion_window_in_days = 30
  primary_key_arn         = aws_kms_key.primary.arn
  policy                  = aws_kms_key.primary.policy
}

resource "aws_kms_alias" "replica_alias" {
  region = var.secondary_aws_region

  name          = "alias/kosli-dedicated-cross-account-key"
  target_key_id = aws_kms_replica_key.replica.key_id
}