Managing multi-Region keys

For most actions, you manage multi-Region keys in the same way that you use and manage single-Region keys. You can enable and disable the keys, set and update aliases, key policies, grants, and tags. However, management of multi-Region keys differs in the following ways.

The multi-Region property that you set when you create KMS key is immutable. You cannot convert a single-Region key to multi-Region key or a convert a multi-Region key to a single-Region key.

Updating the primary Region

Every set of related multi-Region keys must have a primary key. But you can change the primary key. This action, known as updating the primary Region, converts the current primary key to a replica key and converts one of the related replica keys to the primary key. You might do this if you need to delete the current primary key while maintaining the replica keys, or to locate the primary key in the same Region as your key administrators.

You can select any related replica key to be the new primary key. Both the primary key and the replica key must be in the Enabled key state when the operation starts.

Even after this operation completes, the process of updating the primary Region might still be in progress for a few more seconds. During this time, the old and new primary keys have a transient key state of Updating. While the key state is Updating, you can use the keys in cryptographic operations, but you cannot replicate the new primary key or perform certain management operations, such as enabling or disabling these keys. Operations such as DescribeKey might display both the old and new primary keys as replicas. The Enabled key state is restored when the update is complete.

Suppose you have a primary key in US East (N. Virginia) (us-east-1) and a replica key in Europe (Ireland) (eu-west-1). You can use the update feature to change the primary key in US East (N. Virginia) (us-east-1) to a replica key and change the replica key in Europe (Ireland) (eu-west-1) to the primary key.

When the update process completes, the multi-Region key in the Europe (Ireland) (eu-west-1) Region is a multi-Region primary key and the key in the US East (N. Virginia) (us-east-1) Region is its replica key. If there are other related replica keys, they become replicas of the new primary key. The next time that Amazon KMS synchronizes the shared properties of the multi-Region keys, it will get the shared properties from the new primary key and copy them to its replica keys, including the former primary key.

The update operation has no effect on the key ARN of any multi-Region key. It also has no effect on shared properties, such as the key material, or on independent properties, such as the key policy. However, you might want to update the key policy of the new primary key. For example, you might want to add kms:ReplicateKey permission for trusted principals to the new primary key and remove it from the new replica key.

The Updating key state

The process of updating a primary Region takes a bit longer than the brief eventual consistency delay that affects most Amazon KMS operations. The process might still be in progress after the UpdatePrimaryRegion operation returns or you've completed the update procedure in the console. Operations such as DescribeKey might display both the old and new primary keys as replicas until the process completes.

During the process of updating the primary Region, the old primary key and new primary key are in the Updating key state. When the update process completes successfully, both keys return to the Enabled key state. While in the Updating state, some management operations, such as enabling and disabling the keys, are not available. However, you can continue to use both keys in cryptographic operations without interruption. For information about the effect of the Updating key state, see Key states of Amazon KMS keys.

Updating a primary Region (console)

You can update the primary key in the Amazon KMS console. Start on the key details page for the current primary key.

Updating a primary Region (Amazon KMS API)

To change the primary key in a set of related multi-Region keys, use the UpdatePrimaryRegion operation.

$ aws kms update-primary-region \
      --key-id arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab \
      --primary-region eu-west-1

$ aws kms describe-key \
      --key-id arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab \

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

Rotating multi-Region keys

You can enable and disable automatic rotation and perform on-demand rotation of the key material in multi-Region keys. Key rotation is a shared property of multi-Region keys.

You enable and disable automatic key rotation only on the primary key. You initiate on-demand rotation only on the primary key.

This pattern ensures that related multi-Region keys are fully interoperable. Any multi-Region key can decrypt any ciphertext encrypted by a related multi-Region key, even if the ciphertext was encrypted before the key was created.

Automatic key rotation is not supported on asymmetric KMS keys or KMS keys with imported key material. For information about automatic and on-demand key rotation, see Rotating Amazon KMS keys.

Downloading public keys

When you create a multi-Region asymmetric KMS key, Amazon KMS creates an RSA or elliptic curve (ECC) key pair for the primary key. Then it copies that key pair to every replica of the primary key. As a result, you can download the public key from the primary key or any of its replica keys. You will always get the same key material.

For information about downloading and using public keys outside of Amazon KMS, see Special considerations for downloading public keys. For instructions, see Downloading public keys.