Key Management Service:Best practices for using KMS instances

Step 1: Use a CMK as the default key

1. Log on to the KMS console. In the top navigation bar, select the required region. In the left-side navigation pane, click Instances.

2. On the Instances page, click the Default Key Management tab.



3. Find the CMK and click Enable in the Actions column. In the Create Key dialog box, configure parameters and click OK.

Parameter	Description
Key Alias	The alias of the CMK. The alias can contain letters, digits, underscores (_), hyphens (-), and forward slashes (/).
Description	The description of the CMK.
Advanced Settings	The key material origin. Key Management Service: KMS generates key material. External: You must import key material from an external source. For more information, see Import key material into a symmetric key.

Step 2: Configure the encryption settings of the system disk when you create an ECS instance

For more information about the key types and operations supported by KMS for server-side encryption in Alibaba Cloud services, see the documentation of the corresponding Alibaba Cloud service.

1. Log on to the ECS console.

2. In the left-side navigation pane, choose Instances & Images > Instances.

3. In the top navigation bar, select the region and resource group of the resource that you want to manage.

4. On the Instances page, click Create Instance.

5. In the Basic Configurations step, perform the following operations.

   Note

   This step describes how to configure the encryption settings of the system disk when you create an instance. For information about other instance settings, see Create an instance on the Custom Launch tab.

   1. Select a region and a zone in the Region section and select an instance type in the Instance Type section.

   2. Select Public Image or Custom Image in the Image section.

   3. Select Enhanced SSD (ESSD) and specify a capacity for the system disk in the Storage section.

   4. Select Disk Encryption and then select the CMK that you created in the KMS console from the Default Service CMK drop-down list.

      Note

      If you create an ECS instance in the China (Nanjing - Local Region), China (Fuzhou - Local Region), Thailand (Bangkok), or South Korea (Seoul) region, you cannot select custom keys with imported key material as encryption keys.

      After the system disk is encrypted, a tag is automatically added to the CMK that is used to encrypt the system disk. The key of the tag is acs:ecs:disk-encryption, and the value of the tag is true. You can log on to the KMS console and view the CMK ID and the tag that is added to the CMK on the Default Key Management tab of the Instances page.

Prerequisites

• Use Terraform in an on-premises environment

  1. Terraform v0.14 or later is installed.

     Note

     After you install Terraform, you can run the terraform --version command to check the version of Terraform. If the version of Terraform is earlier than v0.14, install Terraform of the required version to overwrite the original version of Terraform.

  2. Your Alibaba Cloud account information is configured.

     Note

     To improve the flexibility and security of permission management, we recommend that you create a Resource Access Management (RAM) user named Terraform. Then, create an AccessKey pair for the RAM user and attach the AliyunKMSCryptoAdminAccess and AliyunKMSSecretAdminAccess policies to the RAM user. The AliyunKMSCryptoAdminAccess policy allows you to manage keys. The AliyunKMSSecretAdminAccess policy allows you to manage secrets. For more information, see Create a RAM user and Grant permissions to a RAM user.

     • (Recommended) Method 1: Configure environment variables to store identity information.

       export ALICLOUD_ACCESS_KEY="******"
       export ALICLOUD_SECRET_KEY="******"
       export ALICLOUD_REGION="******"

     • Method 2: Configure the provider code block in the configuration file to specify identity information.

       provider "alicloud" {
         access_key = "******"
         secret_key = "******"
         region     = "******"
       }

• Use Terraform in Cloud Shell

  Terraform v0.14 or later is installed. If the version does not meet your business requirements, update the version of Terraform. For more information, see Cloud Shell and Use Terraform to manage Alibaba Cloud resources.

Step 1: Purchase a KMS instance in the KMS console

You can purchase KMS instances only in the KMS console. Terraform is not supported.

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

2. On the Instances page, click Create Instance. On the buy page, configure the parameters and click Buy Now.

   Parameter	Description
   Site	The site on which you want to deploy the KMS instance.
   Instance Type	The type of KMS instance. Valid values: Software Key Management: allows you to create your key store. You can manage the lifecycles of keys and use keys for encryption and decryption. Hardware Key Management: allows you to manage the keys that are stored in your hardware security module (HSM) cluster and helps you quickly build a key management center in the cloud. Instances of this type provide simplified API operations for application encryption, meet the data encryption requirements of Alibaba Cloud services and applications, and are suitable for the encryption of data in the cloud. Note service value added: Instances of this type are used to back up and restore data of KMS instances of the software key management type. For more information, see Backup management.
   Region	The region of the KMS instance. For more information, see Regions and zones.
   Computing Performance	The computing performance of the KMS instance. For more information, see QPS quotas.
   Number of Keys	The maximum number of keys that can be created in the KMS instance.
   Number of Secrets	The maximum number of secrets that can be created in the KMS instance.
   Access Management Quantity	The quota of objects that are allowed to access the KMS instance. The quota includes the number of principals that use the resources of the KMS instance and the number of virtual private clouds (VPCs) that are associated with the KMS instance. Default value: 1. For example, if you want to associate the KMS instance with three VPCs and share the instance with two principals, specify a value of at least 5 to meet your business requirements.
   purchase quantity	The number of KMS instances that you want to purchase. Important In most cases, you need to purchase only one KMS instance. If you want to purchase more than one KMS instance, submit a ticket.
   Duration	The subscription duration of the KMS instance. Note You can select Auto-renewal to automatically renew the KMS instance when the instance expires.

3. Read and select Terms of Service, and click Pay to complete the payment.

   The system requires 1 to 5 minutes to create the KMS instance. You can view the created instance on the Instances page.

Step 2: Enable the KMS instance

(Optional) Step 3: View the details of the KMS instance

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

2. On the Instances page, click the tab of the instance type based on your business requirements.

3. Find the KMS instance whose details you want to view and click Manage in the Actions column. You can view the details of the instance on the details page that appears.

Step 4: Create a key in the KMS instance

Use the KMS console

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

2. On the Keys page, select the ID of the instance from the Instance ID drop-down list and 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 for encrypting secret values, select Symmetric Key.
   Key Specifications	The specification of the key.
   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 (/).
   Tag	The tag that is added to the key. A tag consists of a key-value pair. For more information about tags, see What is Tag?.
   Description	The description of the key.

Use Terraform

Prerequisites

• Use Terraform in an on-premises environment

  1. Terraform v0.14 or later is installed.

     Note

     After you install Terraform, you can run the terraform --version command to check the version of Terraform. If the version of Terraform is earlier than v0.14, install Terraform of the required version to overwrite the original version of Terraform.

  2. Your Alibaba Cloud account information is configured.

     Note

     To improve the flexibility and security of permission management, we recommend that you create a Resource Access Management (RAM) user named Terraform. Then, create an AccessKey pair for the RAM user and attach the AliyunKMSCryptoAdminAccess and AliyunKMSSecretAdminAccess policies to the RAM user. The AliyunKMSCryptoAdminAccess policy allows you to manage keys. The AliyunKMSSecretAdminAccess policy allows you to manage secrets. For more information, see Create a RAM user and Grant permissions to a RAM user.

     • (Recommended) Method 1: Configure environment variables to store identity information.

       export ALICLOUD_ACCESS_KEY="******"
       export ALICLOUD_SECRET_KEY="******"
       export ALICLOUD_REGION="******"

     • Method 2: Configure the provider code block in the configuration file to specify identity information.

       provider "alicloud" {
         access_key = "******"
         secret_key = "******"
         region     = "******"
       }

• Use Terraform in Cloud Shell

  Terraform v0.14 or later is installed. If the version does not meet your business requirements, update the version of Terraform. For more information, see Cloud Shell and Use Terraform to manage Alibaba Cloud resources.

Procedure

1. Create a working directory and then create the configuration files named main.tf and variables.tf in the working directory.

   • main.tf: This file is the main file of Terraform and defines the resources that you want to deploy.

     # For more information about the alicloud_kms_key resource, visit https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/kms_key.
     resource "alicloud_kms_key" "key" {
       description                   = "${var.description}"
       dkms_instance_id              = "${var.dkms_instance_id}"
     }
     
     output "key_id" {
       value = alicloud_kms_key.key.id
     }

   • variables.tf: This file contains the custom variables that can be transferred to the main.tf file.

     # The description of the key.
     variable "description" {
       default = "the new key"
     }
     
     # The ID of your KMS instance.
     variable "dkms_instance_id" {
       default = "kst-szz63292789pf2h******"
     }
                                     

2. Run the terraform init command to initialize the Terraform runtime environment.

3. Run the terraform plan command to generate a resource plan.

4. Run the terraform apply command to create a key.

Step 5: Create a secret in the KMS instance

The following example describes how to create a generic secret.

Use the KMS console

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

2. Click the Generic Secrets tab, select the ID of the instance from the Instance ID drop-down list, and then click Create Secret. Then, configure the parameters and click OK.

   Parameter	Description
   Secret Name	The name of the secret.
   Secret Value	The type of the sensitive data that you want to manage. Valid values: Key/Value and Plain Text.
   Initial Version	The initial version of the secret. Default value: v1. You can specify a custom version number.
   CMK	The key that is used to encrypt the values of the secret. Important Your key and secret must belong to the same KMS instance. The key must be a symmetric key. For more information about the symmetric keys supported by KMS, see Key specifications for symmetric and asymmetric encryption. If you are a RAM user or a RAM role, you must have the permissions to call the GenerateDataKey operation by using a key.
   Tag	The tag that is added to the secret. A tag consists of a key-value pair. For more information about tags, see What is Tag?.
   Description	The description of the secret.

Use Terraform

1. Create a working directory and then create the configuration files named main.tf and variables.tf in the working directory.

   • main.tf: This file is the main file of Terraform and defines the resources that you want to deploy.

     # For more information about the alicloud_kms_secret resource, visit https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/kms_secret.
     resource "alicloud_kms_secret" "secret" {
       description                   = "from terraform"
       secret_name                   = "${var.secret_name}"
       secret_data                   = "${var.ENV_SECRET_DATA}"
       version_id                    = "${var.version_id}"
       dkms_instance_id              = "${var.dkms_instance_id}"
       encryption_key_id             = "${var.encryption_key_id}"
     }

   • variables.tf: This file contains the custom variables that can be transferred to the main.tf file.

     // The secret name.
     variable "secret_name" {
       default = "secret_name_sample"
     }
     
     # The secret version information.
     variable "version_id" {
       default = "000000000001"
     }
     
     # The value of the secret. 
     variable "ENV_SECRET_DATA" {
         # Run the export TF_VAR_ENV_SECRET_DATA=xxxxxxxxxx command to specify a value or enter a value when a prompt is displayed. 
             # default = "Secret data sample."
             # Set sensitive to true so that the value is not displayed for Terraform-related tools. 
         sensitive = true
     }
     
     # The ID of your KMS instance.
     variable "dkms_instance_id" {
       default = "kst-szz63292789pf2h******"
     }
     
     # Specify the ID of the key that is used to encrypt the value of the secret. Note: The key and the secret must belong to the same instance. 
     variable "encryption_key_id" {
       default = "key-szz640fd91d99y1******"
     }                      

2. Run the terraform init command to initialize the Terraform runtime environment.

3. Run the terraform plan command to generate a resource plan.

4. Run the terraform apply command to create a secret.

Step 6: Integrate the secret into your application

After you create the secret, you can integrate the secret into your application. This helps prevent sensitive data leaks due to hardcoded secrets in your code. For more information about how to integrate a secret into an application, see SDK references.

VPCs and the KMS instance belong to the same Alibaba Cloud account

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

2. On the Instances page, click the tab of the instance type based on your business requirements.

3. Find the KMS instance that you want to associate with VPCs and click Manage in the Actions column. On the instance details page, click Configure VPCs.

4. In the Configure VPCs dialog box, select the VPCs in the Available VPCs section and click the icon.

5. In the Select vSwitch to Associate with VPC dialog box, select a vSwitch for each VPC and click OK.

6. In the Configure VPCs dialog box, click OK.

VPCs and the KMS instance belong to different Alibaba Cloud accounts

In this example, applications of Alibaba Cloud Account B and Alibaba Cloud Account C access the resources of a KMS instance of Alibaba Cloud Account A.

1. Configure resource sharing to share the vSwitch resources in the VPCs of Alibaba Cloud Account B and Alibaba Cloud Account C with Alibaba Cloud Account A.

   1. Log on to the Resource Management console by using Alibaba Cloud Account B, create a resource share, and share the vSwitch resources in the VPCs that belong to Alibaba Cloud Account B with Alibaba Cloud Account A. Repeat the preceding operations for Alibaba Cloud Account C.

   2. Log on to the Resource Management console by using Alibaba Cloud Account A and accept the resource sharing invitations from Alibaba Cloud Account B and Alibaba Cloud Account C.

   Note

   For more information about how to share resources, see Share resources with an account or Share resources with objects in a resource directory.

2. Log on to the KMS console by using Alibaba Cloud Account A. In the top navigation bar, select the region of the KMS instance that you want to associate with VPCs. In the left-side navigation pane, click Instances.

3. On the Instances page, click the tab of the instance type based on your business requirements.

4. Find the KMS instance and click Manage in the Actions column. On the instance details page, click Configure VPCs.

5. In the Configure VPCs dialog box, select the VPCs in the Available VPCs section and click the icon.

6. In the Select vSwitch to Associate with VPC dialog box, select a vSwitch for each VPC and click OK.

7. In the Configure VPCs dialog box, click OK.

Prerequisites

A resource directory is created. For more information, see What is Resource Directory?.

Step 1: Share a KMS instance as a resource owner

• Use the KMS console

  1. Log on to the KMS console as the resource owner. In the top navigation bar, select the region of the KMS instance. In the left-side navigation pane, click Instances.

  2. On the Instances page, click the tab of the instance type based on your business requirements.

  3. Find the KMS instance that you want to share and click Share Resources in the Actions column.

  4. In the Add to Resource Share panel, click Create. Then, configure the parameters and click OK.

     Parameter	Description
     Resource Share Name	The name of the resource share. You can enter a custom value. The name can contain letters, digits, and the following special characters: periods (.), commas (,). underscores (_), and hyphens (-). The name can be up to 50 characters in length.
     Add Permissions	The permissions of the principal. If you want to check the permissions of principals, you can go to the Permission Library page in the Resource Management console. AliyunRSDefaultPermissionKMSInstance: Principals can use keys for server-side encryption in Alibaba Cloud services. AliyunRSPermissionKMSInstanceReadWrite: Principals can manage keys and use keys for server-side encryption in Alibaba Cloud services. Note For business isolation and risk dispersion purposes, we recommend that you create two resource shares. You can add the AliyunRSPermissionKMSInstanceReadWrite permission to one resource share only for managing keys and add the AliyunRSDefaultPermissionKMSInstance permission to the other resource share for server-side encryption in Alibaba Cloud services.
     Add Principal	The principal. Valid values: Alibaba Cloud Account: Enter the ID of an Alibaba Cloud account in the Principal ID field and click Add to share the KMS instance with the Alibaba Cloud account. This method is used in this example. Resource Directory: Enter the ID of a resource directory in the Principal ID field to share the KMS instance with all members in the resource directory. The ID of a resource directory starts with rd. Example: rd-Y4****. If you create an Alibaba Cloud account in the resource directory or invite an Alibaba Cloud account to join the resource directory after resource sharing, the KMS instance is automatically shared with the new Alibaba Cloud account. Folder: Enter the ID of a folder in the Principal ID field to share the KMS instance with all members in the folder. The ID of a folder starts with fd. Example: fd-gLh1HJ****. If you create an Alibaba Cloud account in the folder or invite an Alibaba Cloud account to join the folder after resource sharing, the KMS instance is automatically shared with the new Alibaba Cloud account. Important The principals and the resource owner must belong to the same resource directory. For more information, see Resource Directory overview. If you share a KMS instance with a principal, the access management quota of the KMS instance is consumed. When you create a resource share, we recommend that you set the Principal Type parameter to Alibaba Cloud Account or Folder. If you set the Principal Type parameter to Resource Directory, all members in the specified resource directory consume the access management quota of the KMS instance. This results in excessive use of the access management quota and unnecessary use of keys in the KMS instance. If you do not specify a principal when you create a resource share, you can specify a principal when you modify the resource share.

     After a KMS instance is shared, Shared is displayed below the ID of the KMS instance. A principal can log on to the KMS console and view the KMS instance. Shared Resource is displayed below the ID of the KMS instance.

• Use the Resource Management console

  For more information, see Share resources only in a resource directory.

Step 2: Use the KMS instance as a principal

Manage keys

If the AliyunRSPermissionKMSInstanceReadWrite permission on the KMS instance is added to the resource share, principals that are added to the resource share can manage the keys of the KMS instance. For example, principals can create keys, configure aliases, and add tags. For more information, see Manage keys.

Use a key to encrypt or decrypt data

If the AliyunRSPermissionKMSInstanceReadWrite permission or the AliyunRSDefaultPermissionKMSInstance permission on the KMS instance is added to the resource share, principals that are added to the resource share can use keys of the KMS instance to perform server-side encryption in Alibaba Cloud services. For more information about server-side encryption, see Integration with KMS and KMS-compatible Alibaba Cloud Services.

What to do next