All Products
Search
Document Center

Key Management Service:Manage a key

Last Updated:May 21, 2024

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.

Create a key

Default key

A default key can be a service key or a customer master key (CMK). A service key is created and managed by an Alibaba Cloud service. You can create and manage a default key of the CMK type. In KMS, creating a default key of the CMK type means enabling a default key of the CMK type. To create a default key of the CMK type, perform the following steps:

Note

You can create only one default key of the CMK type in each region. If you need to create multiple keys, we recommend that you purchase 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 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 (:), 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

    • 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

If you no longer require a key, we recommend that you disable the key. After you confirm that the disabled key does not affect your workloads, you can delete the key. You cannot use disabled keys for cryptographic operations.

  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

After you enable deletion protection for a key, the key cannot be deleted. Deletion protection prevents keys from being accidentally deleted. If you want to delete a key, you must disable deletion protection for the key.

Note

You cannot enable deletion protection for a key that is 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 OK message, click OK.

Schedule deletion of a key

KMS does not support immediate key deletion. If you want to delete a key, you must schedule key deletion. You can specify a scheduled deletion period for a key. When the deletion period elapses, the key is automatically deleted. Before you schedule deletion of a key, you must disable deletion protection for the key.

If you no longer require a key, we recommend that you disable the key. After you confirm that the disabled key does not affect your workloads, you can schedule deletion of the key.

Warning

The system deletes a key when the scheduled deletion period of the key elapses. After the key is deleted, you cannot decrypt the data that is encrypted by using the key or related data keys. Before you delete a key, make sure that the key is no longer in use. If you delete a key that is in use, your services may become unavailable.

  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 Key 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 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, 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. 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 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, 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 Key Details in the Actions column.

  3. On the 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 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, 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.