Creating multi-Region primary keys - Amazon Key Management Service
Creating a multi-Region primary key (console)Creating a multi-Region primary key (Amazon KMS API)
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Creating multi-Region primary keys

You can create a multi-Region primary key in the Amazon KMS console or by using the Amazon KMS API. You can create the primary key in any Amazon Web Services Region where Amazon 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 Amazon 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 Amazon 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.

Important

Do not include confidential or sensitive information in the alias, description, or tags. These fields may appear in plain text in CloudTrail logs and other output.

  1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Web Services 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. Symmetric keys are the default.

    You can create multi-Region symmetric and asymmetric keys, including multi-Region HMAC KMS keys, which are symmetric.

  6. Select your key usage. Encrypt and decrypt is the default.

    For help, see Creating keys, Creating asymmetric KMS keys, or Creating HMAC KMS keys.

  7. Expand Advanced options.

  8. Under Key material origin, to have Amazon 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 (Import key material).

  9. 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.

  10. 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. Amazon 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 Amazon KMS and Using aliases to control access to KMS keys.

  11. (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. Amazon KMS does not synchronize the key descriptions of multi-Region keys.

  12. (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. Amazon 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 Amazon KMS and Using tags to control access to KMS keys.

  13. 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.

    IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see Security best practices in IAM in the IAM User Guide.

    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. Amazon KMS does not synchronize the key policies of multi-Region keys. You can change the key policy of a KMS key at any time.

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

Show moreShow less

Creating a multi-Region primary key (Amazon 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 Amazon Web Services 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. This procedure creates a symmetric encryption key, the default KMS key.

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-.

Important

Do not include confidential or sensitive information in the Description or Tags fields. These fields may appear in plain text in CloudTrail logs and other output.

$ 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": [ ]
      }
    }
}
Show moreShow less