All Products
Search
Document Center

Key Management Service:Manage a key

Last Updated:Mar 03, 2025

Key Management Service (KMS) allows you to manage keys throughout their lifecycles and store the keys in a secure manner. This topic describes how to create a key, disable a key, enable deletion protection for a key, schedule deletion of a key, and add tags to a key.

Important

KMS 1.0 keys are view-only in the 3.0 console, so no actions can be performed on them. If a key lacks operational controls, switch to the 1.0 console through the bottom of the 3.0 console's left-hand navigation. 1.0 keys typically have older creation timestamps.

Create a key

Default CMK

Note
  • A default KMS key is either a service key (managed by the associated Alibaba Cloud service) or a customer master key (CMK). Service keys are not created or managed through the KMS.

  • If you need multiple CMKs, we recommend purchasing a KMS instance with key quotas.

Alibaba Cloud automatically provisions a free customer master key (CMK) per region for each Alibaba Cloud account in KMS. To use this default CMK, just enable it:

  1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys page, click the Default Key tab.

  3. Find the required key, click Enable in the Actions column, configure the parameters, and then click OK.

    Parameter

    Description

    Key Alias

    The alias of the key. The alias can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).

    Description

    The description of the key.

    Advanced Settings

    Key Material Source

    • Key Management Service: KMS generates key material.

    • External: KMS does not generate key material. You must import key material. For more information, see Import key material into a symmetric key.

      Note

      If you select External, you must read and select I understand the implications of using the external key materials.

Software-protected key

Before you create a software-protected key, make sure that you purchased and enabled a KMS instance of the software key management type. For more information, see Purchase and enable a KMS instance.

  1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys page, click the Keys tab, select a KMS instance of the software key management type from the Instance ID drop-down list, and then click Create Key.

  3. In the Create Key panel, configure the parameters and click OK.

    Parameter

    Description

    Key Type

    The type of the key that you want to create. Valid values: Symmetric Key and Asymmetric Key.

    Important

    If you want to create a key to encrypt secret values, select Symmetric Key.

    Key Specifications

    The specification of the key. For more information about key specifications and key algorithms, see Key management types and key specifications.

    • Symmetric key specifications: Aliyun_AES_256

    • Asymmetric key specifications: RSA_2048, RSA_3072, EC_P256, and EC_P256K

    Key Usage

    The usage of the key. Valid values:

    • ENCRYPT/DECRYPT: encrypts or decrypts data.

    • SIGN/VERIFY: signs data or verifies a digital signature.

    Key Alias

    The alias of the key. The alias can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).

    Label

    The tag that you want to add to the key. You can use tags to classify and manage keys. A tag consists of a key-value pair.

    Note
    • The format of the tag key and tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal signs (=), colons (:), and at signs (@).

    • A tag key cannot start with aliyun or acs:.

    • You can configure up to 20 key-value pairs for each key.

    Automatic Rotation

    Specifies whether to enable automatic key rotation. Automatic key rotation is supported only for symmetric keys and is enabled by default. For more information, see Configure key rotation.

    Rotation Period

    The rotation period. Valid values: 7 to 365. Units: days.

    Description

    The description of the key.

    Advanced Settings

    The policy settings of the key.

    • Default Policy: If the key is used by the current Alibaba Cloud account or the Alibaba Cloud account in a resource share, select Default Policy.

      • If the KMS instance is not shared with other accounts, only the current Alibaba Cloud account can manage and use the key.

      • If the KMS instance is shared with other accounts, the supported operations vary. For example, an instance named KMS Instance A is shared with Alibaba Cloud Account 2 by using Alibaba Cloud Account 1.

        • Keys created by Alibaba Cloud Account 1: Only Alibaba Cloud Account 1 can manage and use the keys.

        • Keys created by Alibaba Cloud Account 2: Both Alibaba Cloud Account 1 and Alibaba Cloud Account 2 can manage and use the keys.

    • Custom Policy: If you want to grant permissions to a Resource Access Management (RAM) user, RAM role, or other accounts to use the key, select Custom Policy.

      Important

      Administrators and users do not consume Access Management Quota. If you select another account, the quota of Access Management of the KMS instance is consumed. The quota is calculated based on the number of primary accounts. If you cancel the authorization, wait about 5 minutes and then check the quota. The quota is refunded.

      • An administrator can manage the key. Cryptographic operations are not supported. You can select RAM users and RAM roles within the current Alibaba Cloud account.

        Permissions supported by administrators

        {
        	"Statement": [
        		{
        			"Action": [
        				"kms:List*",
        				"kms:Describe*",
        				"kms:Create*",
        				"kms:Enable*",
        				"kms:Disable*",
        				"kms:Get*",
        				"kms:Set*",
        				"kms:Update*",
        				"kms:Delete*",
        				"kms:Cancel*",
        				"kms:TagResource",   
        				"kms:UntagResource", 
        				"kms:ImportKeyMaterial",
        				"kms:ScheduleKeyDeletion"
        			]
        		}
        	]
        }
      • A user can use the key to perform cryptographic operations. You can select RAM users and RAM roles within the current Alibaba Cloud account.

        Permissions supported by users

         {
            "Statement": [
                {
                    "Action": [
                        "kms:Encrypt",
                        "kms:Decrypt",
        								"kms:GenerateDataKey",
        								"kms:GenerateAndExportDataKey",
                        "kms:AsymmetricEncrypt",
                        "kms:AsymmetricDecrypt",
                        "kms:DescribeKey",
                        "kms:DescribeKeyVersion",
                        "kms:ListKeyVersions",
                        "kms:ListAliasesByKeyId",
        							  "kms:TagResource"
                    ]
                }
            ]
        }
      • A cross-account user can use the key for encryption and decryption. You can select RAM users and RAM roles within other Alibaba Cloud accounts.

        • RAM user: The name of the RAM user is in the acs:ram::<userId>:user/<ramuser> format. Example: acs:ram::119285303511****:user/testpolicyuser.

        • RAM role: The name of the RAM role is in the acs:ram::<userId>:role/<ramrole> format. Example: acs:ram::119285303511****:role/testpolicyrole.

          Note

          After you grant permissions to a RAM user or RAM role, you must use the Alibaba Cloud account of the RAM user or RAM role to authorize the RAM user or RAM role to use the key in RAM. Then, the RAM user or RAM role can use the key.

          For more information, see Use RAM to manage access to KMS resources, Grant permissions to a RAM user, and Grant permissions to a RAM role.

        Permissions supported by cross-account users

         {
            "Statement": [
                {
                    "Action": [
                        "kms:Encrypt",
                        "kms:Decrypt",
        								"kms:GenerateDataKey",
        								"kms:GenerateAndExportDataKey",
                        "kms:AsymmetricEncrypt",
                        "kms:AsymmetricDecrypt",
                        "kms:DescribeKey",
                        "kms:DescribeKeyVersion",
                        "kms:ListKeyVersions",
                        "kms:ListAliasesByKeyId",
        							  "kms:TagResource"
                    ]
                }
            ]
        }

Hardware-protected key

Before you create a hardware-protected key, make sure that you purchased and enabled a KMS instance of the hardware key management type. For more information, see Purchase and enable a KMS instance.

  1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys page, click the Keys tab, select a KMS instance of the hardware key management type from the Instance ID drop-down list, and then click Create Key.

  3. In the Create Key panel, configure the parameters and click OK.

    Parameter

    Description

    Key Type

    The type of the key that you want to create. Valid values: Symmetric Key and Asymmetric Key.

    Important

    If you want to create a key to encrypt secret values, select Symmetric Key.

    Key Specifications

    The specification of the key. For more information about key specifications and key algorithms, see Key management types and key specifications.

    • Symmetric key specifications: Aliyun_AES_256, Aliyun_AES_192, Aliyun_AES_128,

    • Asymmetric key specifications: RSA_2048, RSA_3072, RSA_4096, EC_P256, EC_P256K,

    Key Usage

    The usage of the key. Valid values:

    • ENCRYPT/DECRYPT: encrypts or decrypts data.

    • SIGN/VERIFY: signs data or verifies a digital signature.

    Key Alias

    The alias of the key. The alias can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).

    Label

    The tag that you want to add to the key. You can use tags to classify and manage keys. A tag consists of a key-value pair.

    Note
    • The format of the tag key and tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal signs (=), colons (:), and at signs (@).

    • A tag key cannot start with aliyun or acs:.

    • You can configure up to 20 key-value pairs for each key.

    Description

    The description of the key.

    Advanced Settings

    Policy Settings

    • Default Policy: If the key is used by the current Alibaba Cloud account or the Alibaba Cloud account in a resource share, select Default Policy.

      • If the KMS instance is not shared with other accounts, only the current Alibaba Cloud account can manage and use the key.

      • If the KMS instance is shared with other accounts, the supported operations vary. For example, an instance named KMS Instance A is shared with Alibaba Cloud Account 2 by using Alibaba Cloud Account 1.

        • Keys created by Alibaba Cloud Account 1: Only Alibaba Cloud Account 1 can manage and use the keys.

        • Keys created by Alibaba Cloud Account 2: Both Alibaba Cloud Account 1 and Alibaba Cloud Account 2 can manage and use the keys.

    • Custom Policy: If you want to grant permissions to a Resource Access Management (RAM) user, RAM role, or other accounts to use the key, select Custom Policy.

      Important

      Administrators and users do not consume Access Management Quota. If you select another account, the quota of Access Management of the KMS instance is consumed. The quota is calculated based on the number of primary accounts. If you cancel the authorization, wait about 5 minutes and then check the quota. The quota is refunded.

      • An administrator can manage the key. Cryptographic operations are not supported. You can select RAM users and RAM roles within the current Alibaba Cloud account.

        Permissions supported by administrators

        {
        	"Statement": [
        		{
        			"Action": [
        				"kms:List*",
        				"kms:Describe*",
        				"kms:Create*",
        				"kms:Enable*",
        				"kms:Disable*",
        				"kms:Get*",
        				"kms:Set*",
        				"kms:Update*",
        				"kms:Delete*",
        				"kms:Cancel*",
        				"kms:TagResource",   
        				"kms:UntagResource", 
        				"kms:ImportKeyMaterial",
        				"kms:ScheduleKeyDeletion"
        			]
        		}
        	]
        }
      • A user can use the key to perform cryptographic operations. You can select RAM users and RAM roles within the current Alibaba Cloud account.

        Permissions supported by users

         {
            "Statement": [
                {
                    "Action": [
                        "kms:Encrypt",
                        "kms:Decrypt",
        								"kms:GenerateDataKey",
        								"kms:GenerateAndExportDataKey",
                        "kms:AsymmetricEncrypt",
                        "kms:AsymmetricDecrypt",
                        "kms:DescribeKey",
                        "kms:DescribeKeyVersion",
                        "kms:ListKeyVersions",
                        "kms:ListAliasesByKeyId",
        							  "kms:TagResource"
                    ]
                }
            ]
        }
      • A cross-account user can use the key for encryption and decryption. You can select RAM users and RAM roles within other Alibaba Cloud accounts.

        • RAM user: The name of the RAM user is in the acs:ram::<userId>:user/<ramuser> format. Example: acs:ram::119285303511****:user/testpolicyuser.

        • RAM role: The name of the RAM role is in the acs:ram::<userId>:role/<ramrole> format. Example: acs:ram::119285303511****:role/testpolicyrole.

          Note

          After you grant permissions to a RAM user or RAM role, you must use the Alibaba Cloud account of the RAM user or RAM role to authorize the RAM user or RAM role to use the key in RAM. Then, the RAM user or RAM role can use the key.

          For more information, see Use RAM to manage access to KMS resources, Grant permissions to a RAM user, and Grant permissions to a RAM role.

        Permissions supported by cross-account users

         {
            "Statement": [
                {
                    "Action": [
                        "kms:Encrypt",
                        "kms:Decrypt",
        								"kms:GenerateDataKey",
        								"kms:GenerateAndExportDataKey",
                        "kms:AsymmetricEncrypt",
                        "kms:AsymmetricDecrypt",
                        "kms:DescribeKey",
                        "kms:DescribeKeyVersion",
                        "kms:ListKeyVersions",
                        "kms:ListAliasesByKeyId",
        							  "kms:TagResource"
                    ]
                }
            ]
        }

    Key Material Source

External Key

  • Make sure that you purchase and enable a KMS instance of the external key management type. For more information, see Purchase and enable a KMS instance.

  • Make sure that a key is created in the key management infrastructure (KMI) by using an external key instance (XKI) proxy and the ID of the key is recorded. For more information, see the KMS documentation.

  1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys page, click the Keys tab, select a KMS instance of the external key management type from the Instance ID drop-down list, and then click Create Key.

  3. In the Create Key panel, configure the parameters and click OK.

    Parameter

    Description

    External Key ID

    The key ID of the key generated by the XKI proxy.

    Note

    You can use the same external key ID to create one or more KMS keys.

    Key Specifications

    The specification of the key. For more information about key specifications and key algorithms, see Key types and specifications.

    Aliyun_AES_256

    Key Usage

    The usage of the key.

    ENCRYPT/DECRYPT: encrypts or decrypts data.

    Key Alias

    The alias of the key. The alias can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).

    Tag

    The tag that you want to add to the key. You can use tags to classify and manage keys. A tag consists of a key-value pair.

    Note
    • A tag key or a tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal sign (=), colons (:), at signs (@), and spaces.

    • A tag key cannot start with aliyun or acs:.

    • You can configure up to 20 key-value pairs for each key.

    Description

    The description of the key.

    Advanced Settings

    • Default Policy: If the key is used by the current Alibaba Cloud account or the Alibaba Cloud account in a resource share, select Default Policy.

      • If the KMS instance is not shared with other accounts, only the current Alibaba Cloud account can manage and use the key.

      • If the KMS instance is shared with other accounts, the supported operations vary. For example, an instance named KMS Instance A is shared with Alibaba Cloud Account 2 by using Alibaba Cloud Account 1.

        • Keys created by Alibaba Cloud Account 1: Only Alibaba Cloud Account 1 can manage and use the keys.

        • Keys created by Alibaba Cloud Account 2: Both Alibaba Cloud Account 1 and Alibaba Cloud Account 2 can manage and use the keys.

    • Custom Policy: If you want to grant permissions to a Resource Access Management (RAM) user, RAM role, or other accounts to use the key, select Custom Policy.

      Important

      Administrators and users do not consume Access Management Quota. If you select another account, the quota of Access Management of the KMS instance is consumed. The quota is calculated based on the number of primary accounts. If you cancel the authorization, wait about 5 minutes and then check the quota. The quota is refunded.

      • An administrator can manage the key. Cryptographic operations are not supported. You can select RAM users and RAM roles within the current Alibaba Cloud account.

        Permissions supported by administrators

        {
        	"Statement": [
        		{
        			"Action": [
        				"kms:List*",
        				"kms:Describe*",
        				"kms:Create*",
        				"kms:Enable*",
        				"kms:Disable*",
        				"kms:Get*",
        				"kms:Set*",
        				"kms:Update*",
        				"kms:Delete*",
        				"kms:Cancel*",
        				"kms:TagResource",   
        				"kms:UntagResource", 
        				"kms:ImportKeyMaterial",
        				"kms:ScheduleKeyDeletion"
        			]
        		}
        	]
        }
      • A user can use the key to perform cryptographic operations. You can select RAM users and RAM roles within the current Alibaba Cloud account.

        Permissions supported by users

         {
            "Statement": [
                {
                    "Action": [
                        "kms:Encrypt",
                        "kms:Decrypt",
        								"kms:GenerateDataKey",
        								"kms:GenerateAndExportDataKey",
                        "kms:AsymmetricEncrypt",
                        "kms:AsymmetricDecrypt",
                        "kms:DescribeKey",
                        "kms:DescribeKeyVersion",
                        "kms:ListKeyVersions",
                        "kms:ListAliasesByKeyId",
        							  "kms:TagResource"
                    ]
                }
            ]
        }
      • A cross-account user can use the key for encryption and decryption. You can select RAM users and RAM roles within other Alibaba Cloud accounts.

        • RAM user: The name of the RAM user is in the acs:ram::<userId>:user/<ramuser> format. Example: acs:ram::119285303511****:user/testpolicyuser.

        • RAM role: The name of the RAM role is in the acs:ram::<userId>:role/<ramrole> format. Example: acs:ram::119285303511****:role/testpolicyrole.

          Note

          After you grant permissions to a RAM user or RAM role, you must use the Alibaba Cloud account of the RAM user or RAM role to authorize the RAM user or RAM role to use the key in RAM. Then, the RAM user or RAM role can use the key.

          For more information, see Use RAM to manage access to KMS resources, Grant permissions to a RAM user, and Grant permissions to a RAM role.

        Permissions supported by cross-account users

         {
            "Statement": [
                {
                    "Action": [
                        "kms:Encrypt",
                        "kms:Decrypt",
        								"kms:GenerateDataKey",
        								"kms:GenerateAndExportDataKey",
                        "kms:AsymmetricEncrypt",
                        "kms:AsymmetricDecrypt",
                        "kms:DescribeKey",
                        "kms:DescribeKeyVersion",
                        "kms:ListKeyVersions",
                        "kms:ListAliasesByKeyId",
        							  "kms:TagResource"
                    ]
                }
            ]
        }

Disable a key

Only default or purchased CMKs can be disabled (service keys are not supported). Disable unused keys, then delete them after verifying no impact on your workloads. Disabled keys are unusable.

  1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys page, click the Keys or Default Key tab, find the key that you want to disable, and then click Disable in the Actions column.

  3. In the Disable Key dialog box, confirm the on-screen information and click OK.

    You can click Key Association to check whether the key is used for server-side encryption in Alibaba Cloud services. For more information, see Check key association.

    After the key is disabled, the status of the key changes from Enabling to Disabled. To re-enable the key, click Enable.

Enable deletion protection

Only default or purchased CMKs support deletion protection (service keys are not supported). Enabling deletion protection prevents accidental key deletion. To delete a protected key, disable the protection first.

You cannot enable deletion protection for a key in the Pending Deletion state.

  1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys page, click the Keys or Default Key tab, find the key for which you want to enable deletion protection, and then click Details in the Actions column.

  3. On the details page that appears, turn on Deletion Protection.

  4. In the Confirm message, click Enable.

Schedule deletion of a key

KMS does not support immediate key deletion. To delete a key, you must schedule a deletion, specifying a time period. Only default or purchased CMKs support scheduled deletion (service keys are not supported). Before scheduling deletion, disable the key and confirm it won't affect your workloads.

Warning

After the scheduled time, the key and its encrypted data are irretrievably deleted. Ensure the key is not in use before scheduling deletion.

  1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys or Default Key tab, find the key that you want to delete, click the image.png icon in the Actions column, and then click Schedule Deletion.

  3. In the Schedule Deletion dialog box, confirm the on-screen information, specify the scheduled deletion period, and then click OK.

    You can click Key Association to check whether the key is used for server-side encryption in Alibaba Cloud services. For more information, see Check key association.

    After you specify a scheduled deletion period, the status of the key changes from Enabling to Pending Deletion. You cannot use a key in the Pending Deletion state to encrypt data, decrypt data, or generate data keys. You can click Cancel Deletion to cancel the deletion before the scheduled deletion period elapses.

Download the public key of an asymmetric key

After you create an asymmetric key, you can download the public key of the asymmetric key. You cannot download the private key of the asymmetric key.

  1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys or Default Key tab, find the key that you want to manage and click Details in the Actions column.

  3. On the Key Version tab, click View Public Key in the Actions column.

  4. In the View Public Key message, click Download.

Check key association

You can check whether a key is used for server-side encryption in Elastic Compute Service (ECS). You cannot check whether a key is used for server-side encryption in other cloud services or data encryption in self-managed applications.

  1. Log on to the Key Management Service console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys or Default Key tab, find the key that you want to manage and click Details in the Actions column.

  3. On the Key Association tab, click Check. Wait for about 1 minute and click the image.png icon to view the check result.

    • Cloud Service: the cloud service in which the key is used for server-side encryption. Only ECS is supported.

    • Last Called At: the most recent time when a cloud service accessed the key.

      Note

      If a cloud service accessed the key within the last 365 days, the time is displayed. If a cloud service accessed the key 365 days ago, the time is not displayed.

    • Check Status: the check status. If the check fails, refresh and try again.

    • Service Entry: the entry point to query the resources that are encrypted by using the key.

      Important

      The ECS Disk and Key Association and ECS Snapshot and Key Association pages display only the disks or snapshots on which the current account has access permissions.

    If the key is still in use, do not delete the key unless otherwise required.

Add tags to keys

You can use tags to classify and manage keys. A tag consists of a key-value pair. You can add tags only to keys that are created in KMS instances. You cannot add tags to default keys.

Note
  • The format of the tag key and tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal signs (=), colons (:), and at signs (@).

  • A tag key cannot start with aliyun or acs:.

  • You can configure up to 20 key-value pairs for each key.

Add tags to a key

Solution

Operation

Method 1: Add tags on the Keys page

  1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys page, select the required instance ID from the Instance ID drop-down list, find the key to which you want to add tags, and then click the image.png icon in the Tag column.

  3. Click Add Tag. In the Edit Tag dialog box, enter multiple Tag Key and Tag Value and then click OK. In the message that appears, click Close.

    In the Edit Tag dialog box, you can change the tag values and remove multiple tags at a time.

Method 2: Add tags on the Key Details page

  1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys page, select the required instance ID from the Instance ID drop-down list, find the key to which you want to add tags, and then click Details in the Actions column.

  3. On the instanace details page, click the image.png icon next to Tag.

  4. In the Edit Tag dialog box, enter multiple Tag Key and Tag Value and then click OK. In the message that appears, click Close.

    In the Edit Tag dialog box, you can change the tag values and remove multiple tags at a time.

Add tags to multiple keys at a time

  1. Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.

  2. On the Keys page, select the required instance ID from the Instance ID drop-down list, and then select the keys whose tags you want to manage in the key list.

    • Add tags: In the lower part of the key list, click Add Tag. In the Add Tag dialog box, enter multiple Tag Key and Tag Value, and then click OK. In the message that appears, click Close.

    • Remove tags: In the lower part of the key list, click Remove Tag. In the Batch Remove dialog box, select the tags that you want to remove and click Remove. In the message that appears, click Close.