Creating multi-Region replica keys - Amazon Key Management Service
Replica RegionsCreating replica keys (console)Creating a replica 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 replica keys

You can create a multi-Region replica key in the Amazon KMS console, by using the ReplicateKey operation, or by using a Amazon CloudFormation template. You cannot use the CreateKey operation to create a replica key.

You can use these procedures to replicate any multi-Region primary key, including a symmetric encryption KMS key, an asymmetric KMS key, or an HMAC KMS key.

When this operation completes, the new replica key has a transient key state of Creating. This key state changes to Enabled (or PendingImport) after a few seconds when the process of creating the new replica key is complete. While the key state is Creating, you can manage key, but you cannot yet use it in cryptographic operations. If you are creating and using the replica key programmatically, retry on KMSInvalidStateException or call DescribeKey to check its KeyState value before using it.

If you mistakenly delete a replica key, you can use this procedure to recreate it. If you replicate the same primary key in the same Region, the new replica key you create will have the same shared properties as the original replica key.

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.

Learn more

Replica Regions

You typically choose to replicate a multi-Region key into an Amazon Web Services Region based on your business model and regulatory requirements. For example, you might replicate a key into Regions where you keep your resources. Or, to comply with a disaster recovery requirement, you might replicate a key into geographically distant Regions.

The following are the Amazon KMS requirements for replica Regions. If the Region that you choose doesn't comply with these requirements, attempts to replicate a key fail.

  • One related multi-Region key per Region — You can't create a replica key in the same Region as its primary key, or in the same Region as another replica of the primary key.

    If you try to replicate a primary key in a Region that already has a replica of that primary key, the attempt fails. If the current replica key in the Region is in the PendingDeletion key state, you can cancel the replica key deletion or wait until the replica key is deleted.

  • Multiple unrelated multi-Region keys in the same Region — You can have multiple unrelated multi-Region keys in the same Region. For example, you can have two multi-Region primary keys in the us-east-1 Region. Each of the primary keys can have a replica key in us-west-2 Region.

  • Regions in the same partition — The replica key Region must be in the same Amazon partition as the primary key Region.

  • Region must be enabled — If a Region is disabled by default, you cannot create any resources in that Region until it is enabled for your Amazon Web Services account.

Creating replica keys (console)

In the Amazon KMS console, you can create one or many replicas of a multi-Region primary key in the same operation.

This procedure is similar to creating a standard single-Region KMS key in the console. However, because a replica key is based on the primary key, you do not select values for shared properties, such as the key spec (symmetric or asymmetric), key usage, or key origin.

You do specify properties that are not shared, including an alias, tags, a description, and a key policy. As a convenience, the console displays the current property values of the primary key, but you can change them. Even if you keep the primary key values, Amazon KMS does not keep these values synchronized.

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. Select the key ID or alias of a multi-Region primary key. This opens the key details page for the KMS key.

    To identify a multi-Region primary key, use the tool icon in the upper right corner to add the Regionality column to the table.

  5. Choose the Regionality tab.

  6. In the Related multi-Region keys section, choose Create new replica keys.

    The Related multi-Region keys section displays the Region of the primary key and its replica keys. You can use this display to help you choose the Region for your new replica key.

  7. Choose one or more Amazon Web Services Regions. This procedure creates a replica key in each of the Regions you select.

    The menu includes only Regions in the same Amazon partition as the primary key. Regions that already have a related multi-Region key are displayed, but not selectable. You might not have permission to replicate a key into all of the Regions on the menu.

    When you are finished choosing Regions, close the menu. The Regions you chose are displayed. To cancel replication into a Region, choose the X beside the Region name.

  8. Type an alias for the replica key.

    The console displays one of the current aliases of the primary key, but you can change it. You can give your multi-Region primary key and its replicas the same alias or different aliases. Aliases are not a shared property of multi-Region keys. Amazon KMS does not synchronize the aliases of multi-Region keys.

    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.

  9. (Optional) Type a description of the replica key.

    The console displays the current description of the primary key, but you can change it. 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.

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

    The console displays the tags currently attached to the primary key, but you can change them. 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.

    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.

  11. Select the IAM users and roles that can administer the replica key.

    Note

    IAM policies can give other IAM users and roles permission to manage the replica keys.

    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 begins the process of creating a key policy for the replica key. The console displays the current key policy of the primary key, but you can change it. 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 key policies. You can change the key policy of any KMS key at any time.

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

Show moreShow less

Creating a replica key (Amazon KMS API)

To create a multi-Region replica key, use the ReplicateKey operation. You cannot use the CreateKey operation to create a replica key. This operation creates one replica key at a time. The Region that you specify must comply with the Region requirements for replica keys.

When you use the ReplicateKey operation, you don't specify values for any shared properties of multi-Region keys. Shared property values are copied from the primary key and kept synchronized. However, you can specify values for properties that are not shared. Otherwise, Amazon KMS applies the standard default values for KMS keys, not the values of the primary key.

Note

If you don't specify values for the Description, KeyPolicy, or Tags parameters, Amazon KMS creates the replica key with an empty string description, the default key policy, and no tags.

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.

For example, the following command creates a multi-Region replica key in the Asia Pacific (Sydney) Region (ap-southeast-2). This replica key is modeled on the primary key in the US East (N. Virginia) Region (us-east-1), which is identified by the value of the KeyId parameter. This example accepts default values for all other properties, including the key policy.

The response describes the new replica key. It includes fields for shared properties, such as the KeyId, KeySpec, KeyUsage, and key material origin (Origin). It also includes properties that are independent of the primary key, such as the Description, key policy (ReplicaKeyPolicy), and tags (ReplicaTags).

The response also includes the key ARN and region of the primary key and all of its replica keys, including the one that was just created in the ap-southeast-2 Region. In this example, the ReplicaKey element shows that this primary key was already replicated in the Europe (Ireland) Region (eu-west-1).

$ aws kms replicate-key \
    --key-id arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab \
    --replica-region ap-southeast-2
{
    "ReplicaKeyMetadata": {
        "MultiRegion": true,
        "MultiRegionConfiguration": {
            "MultiRegionKeyType": "REPLICA",
            "PrimaryKey": {
                "Arn": "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
                "Region": "us-east-1"
            },
            "ReplicaKeys": [
                {
                    "Arn": "arn:aws:kms:ap-southeast-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
                    "Region": "ap-southeast-2"
                },
                {
                    "Arn": "arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
                    "Region": "eu-west-1"
                }
            ]
        },
        "AWSAccountId": "111122223333",
        "Arn": "arn:aws:kms:ap-southeast-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab",
        "CreationDate": 1607472987.918,
        "Description": "",
        "Enabled": true,
        "KeyId": "mrk-1234abcd12ab34cd56ef1234567890ab",
        "KeyManager": "CUSTOMER",
        "KeySpec": "SYMMETRIC_DEFAULT",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT_DECRYPT",
        "Origin": "AWS_KMS",
        "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
        "EncryptionAlgorithms": [
            "SYMMETRIC_DEFAULT"
        ]
    },
    "ReplicaKeyPolicy": "{\n  \"Version\" : \"2012-10-17\",\n  \"Id\" : \"key-default-1\",...,
    "ReplicaTags": []
}
Show moreShow less