Creating multi-Region primary keys - AWS Key Management Service

Creating multi-Region primary keys

You can create a multi-Region primary key in the AWS KMS console or by using the AWS KMS API. You can create the primary key in any AWS Region where AWS KMS supports multi-Region keys.

To create a multi-Region primary key, the principal needs the same permissions that they need to create any KMS key, including the kms:CreateKey permission in an IAM policy. The principal also needs the iam:CreateServiceLinkedRole permission. You can use the kms:MultiRegionKeyType condition key to allow or deny permission to create multi-Region primary keys.

These instructions create a multi-Region primary key with key material that AWS KMS generates. To create a multi-Region primary key with imported key material, see Creating a primary key with imported key material.

Creating a multi-Region primary key (console)

To create a multi-Region primary key in the AWS KMS console, use the same process that you would use to create any KMS key.. You select a multi-Region key in Advanced options. For complete instructions, see Creating keys.

  1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms.

  2. To change the AWS Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys.

  4. Choose Create key.

  5. Select a symmetric or asymmetric key type. If you choose asymmetric, you need to select the key usage and key spec.

  6. Expand Advanced options.

  7. Under Key material origin, to have AWS KMS generate the key material that your primary and replica keys will share, choose KMS. If you are importing key material into the primary and replica keys, choose External.

  8. Under Multi-Region replication, choose Allow this key to be replicated into other Regions.

    You can't change this setting after you create the KMS key.

  9. Type an alias for the primary key.

    Aliases are not a shared property of multi-Region keys. You can give your multi-Region primary key and its replicas the same alias or different aliases. AWS KMS does not synchronize the aliases of multi-Region keys.

    Note

    Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see ABAC for AWS KMS and Using aliases to control access to KMS keys.

  10. (Optional) Type a description of the primary key.

    Descriptions are not a shared property of multi-Region keys. You can give your multi-Region primary key and its replicas the same description or different descriptions. AWS KMS does not synchronize the key descriptions of multi-Region keys.

  11. (Optional) Type a tag key and an optional tag value. To assign more than one tag to the primary key, choose Add tag.

    Tags are not a shared property of multi-Region keys. You can give your multi-Region primary key and its replicas the same tags or different tags. AWS KMS does not synchronize the tags of multi-Region keys. You can change the tags on KMS keys at any time.

    Note

    Tagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see ABAC for AWS KMS and Using tags to control access to KMS keys.

  12. Select the IAM users and roles that can administer the primary key.

    Note

    IAM policies can give other IAM users and roles permission to manage the KMS key.

    This step starts the process of creating a key policy for the primary key. Key policies are not a shared property of multi-Region keys. You can give your multi-Region primary key and its replicas the same key policy or different key policies. AWS KMS does not synchronize the key policies of multi-Region keys. You can change the key policy of a KMS key at any time.

  13. Complete the steps for creating the key policy, including selecting key administrators. After you review the key policy, choose Finish to create the KMS key.

Creating a multi-Region primary key (AWS KMS API)

To create a multi-Region primary key, use the CreateKey operation. Use the MultiRegion parameter with a value of True.

For example, the following command creates a multi-Region primary key in the caller's AWS Region (us-east-1). It accepts default values for all other properties, including the key policy. The default values for multi-Region primary keys are the same as the default values for all other KMS keys, including the default key policy.

The response includes the MultiRegion element and the MultiRegionConfiguration element with typical sub-elements and values for a multi-Region primary key with no replica keys. The key ID of a multi-Region key always begins with mrk-.

$ aws kms create-key --multi-region { "KeyMetadata": { "Origin": "AWS_KMS", "KeyId": "mrk-1234abcd12ab34cd56ef1234567890ab", "Description": "", "KeyManager": "CUSTOMER", "Enabled": true, "KeySpec": "SYMMETRIC_DEFAULT", "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT", "KeyUsage": "ENCRYPT_DECRYPT", "KeyState": "Enabled", "CreationDate": 1606329032.475, "Arn": "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab", "AWSAccountId": "111122223333", "EncryptionAlgorithms": [ "SYMMETRIC_DEFAULT" ], "MultiRegion": true, "MultiRegionConfiguration": { "MultiRegionKeyType": "PRIMARY", "PrimaryKey": { "Arn": "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab", "Region": "us-east-1" }, "ReplicaKeys": [ ] } } }