Key Management Service:Migrate CMKs in default KMS instances to your KMS instances

Usage notes

• You need to migrate only CMKs in default KMS instances. You do not need to migrate service keys in default KMS instances or CMKs in dedicated KMS instances. For more information about keys in KMS consoles of different versions, see Keys in the KMS consoles of the new version and the old version.

• After a CMK is migrated, data that is encrypted by using the CMK can still be decrypted by using the CMK.

• If you do not migrate CMKs in default KMS instances, you can use the CMKs in the KMS console of the old version, but you cannot increase the key quota.

• You cannot migrate the following CMKs:

  • CMKs with external key material

  • CMKs with automatic rotation enabled

    Important

    If automatic rotation is enabled for a CMK with only one version, you can migrate the CMK after you disable automatic rotation.

  • CMKs with multiple versions

• If your applications are deployed on Alibaba Cloud, you can follow the instructions provided in this topic to migrate CMKs. If your applications are deployed outside Alibaba Cloud, you can contact technical support by using ticket.

• Before you migrate CMKs, we recommend that you understand the capabilities of KMS instances of the hardware key management type or the software key management type. For more information, see Instance selection.

Migration scenarios

Scenario 1: A CMK with KMS-generated key material is used for server-side encryption in Alibaba Cloud services

1. Check whether the CMK can be migrated.

   1. Log on to the KMS console of the old version.

   2. In the left-side navigation pane, click Keys. In the upper part of the page, click Migration Diagnostic Tool.

   3. Read the prompt and click OK. Then, the tool displays whether the CMK can be migrated.

2. Purchase a KMS instance of the hardware key management or software key management type.

   For more information, see Purchase a KMS instance. For more information about how to select a KMS instance, see Instance selection.

3. Contact technical support to migrate the CMK.

   Contact technical support by using ticket. You need to provide the following information: the ID of the CMK that you want to migrate, the migration time window, and the destination KMS instance to which you want to migrate the CMK. We recommend that you migrate the CMK during off-peak hours.

   Note

   Alibaba Cloud performs CMK migration during the migration time window. After the migration is complete, you can view the CMK in the KMS console of the new version. To view the CMK, log on to the KMS console of the new version. On the Keys page, select the KMS instance to be migrated and view the CMK in the key list.

Scenario 2: A CMK with KMS-generated key material is used for data encryption in user-owned applications

1. Check whether the CMK can be migrated.

   1. Log on to the KMS console of the old version.

   2. In the left-side navigation pane, click Keys. In the upper part of the page, click Migration Diagnostic Tool.

   3. Read the prompt and click OK. Then, the tool displays whether the CMK can be migrated.

2. Check whether the CMK can be migrated.

   Condition	Description
   Cryptographic operations	If an application uses ReEncrypt, ExportDataKey, or GenerateAndExportDataKey API operations, the CMK cannot be migrated.
   Network location of an application	If an application and the KMS instance that encrypts the data in the application reside in the same or different virtual private clouds (VPCs), the CMK can be migrated.
   Application development programming languages	Migration SDK for Java, Migration SDK for Go, and Migration SDK for Python are provided to help you migrate the CMK with fewer code modifications. If an application is developed in other programming languages, you cannot migrate the CMK. To submit your CMK migration requirements, you can contact technical support by using ticket.

3. Purchase a KMS instance of the hardware key management or software key management type.

   For more information, see Purchase a KMS instance. For more information about how to select a KMS instance, see Instance selection.

4. Contact technical support to migrate the CMK.

   Contact technical support by using ticket. You need to provide the following information: the ID of the CMK that you want to migrate, the migration time window, and the destination KMS instance to which you want to migrate the CMK. We recommend that you migrate the CMK during off-peak hours.

   Note

   Alibaba Cloud performs CMK migration during the migration time window. After the migration is complete, you can view the CMK in the KMS console of the new version. To view the CMK, log on to the KMS console of the new version. On the Keys page, select the KMS instance to be migrated and view the CMK in the key list.

5. Modify the application.

   Important

   Alibaba Cloud closes the entry point to the KMS console of the old version one month after you migrate the CMK in the default KMS instances. You must modify the application within one month after you migrate the CMK.

   1. Creates an application access point (AAP). For more information, see Access a KMS instance by using an AAP.

   2. Modify the code of the application. The following examples show how to modify the code of an application in different programming languages:

      Java

      Add Maven dependencies

         <!-- add dkms sdk dependency -->
        <dependency>
            <groupId>com.aliyun</groupId>
            <artifactId>alibabacloud-dkms-gcs-sdk</artifactId>
            <version>x.x.x</version>
          </dependency>
      
        <dependency>
            <groupId>com.aliyun.kms</groupId>
            <artifactId>kms-transfer-client</artifactId>
            <version>x.x.x</version>
        </dependency>

      Note

      For the latest version of SDKs, visit alibabacloud-dkms-gcs-java-sdk and alibabacloud-dkms-transfer-java-sdk.

      Code modification

      Note

      The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using the AccessKey pair to perform operations is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. We recommend that you do not save the AccessKey ID and AccessKey Secret in your project code. Otherwise, the AccessKey pair may be leaked and the security of all the resources that belong to your account may be compromised.

      In this example, the AccessKey pair is saved in the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables to implement identity authentication. For more information about how to configure authentication information, see Credentials.

      Sample code before the modification:

      import com.aliyuncs.DefaultAcsClient;
      import com.aliyuncs.IAcsClient;
      import com.aliyuncs.exceptions.ClientException;
      import com.aliyuncs.exceptions.ServerException;
      import com.aliyuncs.profile.DefaultProfile;
      import com.google.gson.Gson;
      import java.util.*;
      import com.aliyuncs.kms.model.v20160120.*;
      
      public class Encrypt {
      
          public static void main(String[] args) {
              DefaultProfile profile = DefaultProfile.getProfile("cn-hangzhou", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
              IAcsClient client = new DefaultAcsClient(profile);
              // The request parameters.
              EncryptRequest request = new EncryptRequest();
              request.setProtocol(ProtocolType.HTTPS);
              request.setAcceptFormat(FormatType.JSON);
              request.setMethod(MethodType.POST);
              request.setKeyId(<keyId>);
              request.setPlaintext(plainText);
      
              try {
                  EncryptResponse response = client.getAcsResponse(request);
                  System.out.println(new Gson().toJson(response));
              } catch (ServerException e) {
                  e.printStackTrace();
              } catch (ClientException e) {
                  System.out.println("ErrCode:" + e.getErrCode());
                  System.out.println("ErrMsg:" + e.getErrMsg());
                  System.out.println("RequestId:" + e.getRequestId());
              }
      
          }
      }

      Sample code after the modification:

      import com.aliyun.kms.KmsTransferAcsClient;
      import com.aliyun.dkms.gcs.openapi.models.Config;
      import com.aliyuncs.IAcsClient;
      import com.aliyuncs.exceptions.ClientException;
      import com.aliyuncs.exceptions.ServerException;
      import com.aliyuncs.profile.DefaultProfile;
      import com.google.gson.Gson;
      import java.util.*;
      import com.aliyuncs.kms.model.v20160120.*;
      
      public class Encrypt {
      
          public static void main(String[] args) {
              DefaultProfile profile = DefaultProfile.getProfile("cn-hangzhou", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
      
              Config config = new Config();
              // The connection protocol. Set the value to https. 
              config.setProtocol("https");
              // The client key of the KMS instance. 
              config.setClientKeyFile("<your-client-key-file>");
              // The password that is used to decrypt the client key of the KMS instance. 
              config.setPassword("<your client key password>");
              // The endpoint of the KMS instance. The endpoint does not contain the scheme https. 
              config.setEndpoint("<service_id>.cryptoservice.kms.aliyuncs.com");
              // The path of the certificate authority (CA) certificate file. You can also specify the content of the CA certificate. 
              config.setCaFilePath("<path/to/yourCaCert>");
              // The content of the CA certificate. 
              //config.setCa("<your-ca-certificate-content");   
              IAcsClient client = new KmsTransferAcsClient(profile, config);
              // The request parameters.
              EncryptRequest request = new EncryptRequest();
              request.setProtocol(ProtocolType.HTTPS);
              request.setAcceptFormat(FormatType.JSON);
              request.setMethod(MethodType.POST);
              request.setKeyId(<keyId>);
              request.setPlaintext(plainText);
      
              try {
                  EncryptResponse response = client.getAcsResponse(request);
                  System.out.println(new Gson().toJson(response));
              } catch (ServerException e) {
                  e.printStackTrace();
              } catch (ClientException e) {
                  System.out.println("ErrCode:" + e.getErrCode());
                  System.out.println("ErrMsg:" + e.getErrMsg());
                  System.out.println("RequestId:" + e.getRequestId());
              }
      
          }
      }

      Python

      Install the dependency package

      • If you use SDK for Python 3, run the following commands:

      $ pip install alibabacloud-dkms-gcs
      $ pip install alibabacloud-dkms-transfer-python

      Note

      For more information, visit alibabacloud-dkms-gcs-python-sdk and alibabacloud-dkms-transfer-python-sdk.

      • If you use SDK for Python 2, run the following commands:

      $ pip install alibabacloud-dkms-gcs-python2
      $ pip install alibabacloud-dkms-transfer-python2

      Note

      For more information, visit alibabacloud-dkms-gcs-python2-sdk and alibabacloud-dkms-transfer-python2-sdk.

      Code modification

      Note

      The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using the AccessKey pair to perform operations is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. We recommend that you do not save the AccessKey ID and AccessKey Secret in your project code. Otherwise, the AccessKey pair may be leaked and the security of all the resources that belong to your account may be compromised.

      In this example, the AccessKey pair is saved in the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables to implement identity authentication. For more information about how to configure authentication information, see Instantiate a client and configure a credential.

      Sample code before the modification:

      from aliyunsdkcore.auth.credentials import AccessKeyCredential
      from aliyunsdkcore.client import AcsClient
      from aliyunsdkkms.request.v20160120.EncryptRequest import EncryptRequest
      
      
      def encrypt():
          credentials = AccessKeyCredential(os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
      
          client = AcsClient(region_id="<your-region-id>", credential=credentials)
      
          request = EncryptRequest()
          request.set_accept_format('json')
          request.set_KeyId("<your-key-id>")
          request.set_Plaintext("<your-plaintext>")
      
          response = client.do_action_with_exception(request)
          print(str(response, encoding='utf-8'))
      
      
      encrypt()

      Sample code after the modification:

      from alibabacloud_dkms_transfer.kms_transfer_acs_client import KmsTransferAcsClient
      from aliyunsdkcore.auth.credentials import AccessKeyCredential
      from aliyunsdkkms.request.v20160120.EncryptRequest import EncryptRequest
      from openapi.models import Config
      
      
      def encrypt():
          config = Config()
          config.protocol = "https"
          config.client_key_file = "<your-client-key-file-path>"
          config.password = "<your-password>"
          config.endpoint = "<your-endpoint>"
      
          credentials = AccessKeyCredential(os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
      
          client = KmsTransferAcsClient(config=config, credential=credentials, verify='<your-ca-certificate-file-path>')
      
          request = EncryptRequest()
          request.set_KeyId("<your-key-id>")
          request.set_Plaintext("<your-plaintext>")
      
          response = client.do_action_with_exception(request)
          print(str(response, encoding='utf-8'))
      
      
      encrypt()

      Go

      Use one of the following methods to install the dependency package

      • Use the go mod file to install dependencies:

      require (
          github.com/aliyun/alibabacloud-dkms-transfer-go-sdk vX.X.X
          github.com/aliyun/alibabacloud-dkms-gcs-go-sdk vX.X.X
          github.com/alibabacloud-go/tea vX.X.X
      )

      • Run the go get commands to obtain the remote code package:

      $ go get -u github.com/aliyun/alibabacloud-dkms-transfer-go-sdk
      $ go get -u github.com/aliyun/alibabacloud-dkms-gcs-go-sdk
      $ go get -u github.com/alibabacloud-go/tea

      Note

      For the latest version of SDK, visit alibabacloud-dkms-gcs-go-sdk and alibabacloud-dkms-transfer-go-sdk.

      Code modification

      Note

      The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using the AccessKey pair to perform operations is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. We recommend that you do not save the AccessKey ID and AccessKey Secret in your project code. Otherwise, the AccessKey pair may be leaked and the security of all the resources that belong to your account may be compromised.

      In this example, the AccessKey pair is saved in the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables to implement identity authentication. For more information about how to configure authentication information, see Instantiate a client and configure a credential.

      Sample code before the modification:

      import (
          "fmt"
          "github.com/aliyun/alibaba-cloud-sdk-go/services/kms"
      )
      
      func main() {
          client, err := kms.NewClientWithAccessKey("<your-region-id>", os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
          if err != nil {
              panic(err)
          }
      
          request := kms.CreateEncryptRequest()
          request.Scheme = "https"
          request.KeyId = "<your cmk id>"
          request.Plaintext = "<your plaintext>"
      
          response, err := client.Encrypt(request)
          if err != nil {
              panic(err)
          }
      
          fmt.Println(response)
      }

      Sample code after the modification:

      import (
          "fmt"
          "github.com/alibabacloud-go/tea/tea"
          "github.com/aliyun/alibaba-cloud-sdk-go/services/kms"
          dedicatedkmsopenapi "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/openapi"
          "github.com/aliyun/alibabacloud-dkms-transfer-go-sdk/sdk"
      )
      
      func main() {
          config := &dedicatedkmsopenapi.Config{
              Protocol:      tea.String("https"),
              ClientKeyFile: tea.String("<your-client-key-file>"),
              Password:      tea.String("<your-client-key-password>"),
              Endpoint:      tea.String("<your-dkms-instance-service-endpoint>"),
          }
      
          client, err := sdk.NewClientWithAccessKey("<your-region-id>", os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"), config)
          if err != nil {
              panic(err)
          }
      
          request := kms.CreateEncryptRequest()
          request.KeyId = "<your cmk id>"
          request.Plaintext = "<your plaintext>"
      
          response, err := client.Encrypt(request)
          if err != nil {
              panic(err)
          }
      
          fmt.Println(response)
      }

Scenario 3: A CMK with external key material is used for server-side encryption in Alibaba Cloud services

You cannot migrate CMKs with external key material.

Scenario 4: A CMK with external key material is used for data encryption in user-owned applications

You cannot migrate CMKs with external key material.

Keys in the consoles of the old version and the new version

• Service keys

  • In the KMS console of the old version

    In the left-side navigation pane, click Keys. In the top navigation bar, select a region. Find a key. If the value in the KMS Instance column is Default and the key alias is in the alias/acs/Cloud service format, the key is a service key.

    

  • In the KMS console of the new version

    In the left-side navigation pane, click Instances. In the top navigation bar, select a region. On the Instances page, click the Default Key Management tab. Find a key. If the value in the KeyManagerType column is Service Key, the key is a service key.

    

• CMKs in default KMS instances

  • In the KMS console of the old version

    In the left-side navigation pane, click Keys. In the top navigation bar, select a region. Find a key. If the value in the KMS Instance column is Default and the key alias is not in the alias/acs/Cloud service format, the key is a CMK.

    

  • In the KMS console of the new version

    In the left-side navigation pane, click Instances. In the top navigation bar, select a region. On the Instances page, click the Default Key Management tab. Find a key. If the value in the KeyManagerType column is CMK, the key is a CMK.

    Important

    In the KMS console of the new version, you can only view CMKs that are used as default keys, but cannot manage the CMKs. For example, you cannot disable a CMK or schedule the deletion of a CMK. If you want to manage the CMKs, go to the KMS console of the old version.

    

• CMKs in dedicated KMS instances

  • In the KMS console of the old version

    In the left-side navigation pane, click Keys. In the top navigation bar, select a region. Find a key. If the value in the KMS Instance column is the ID of a dedicated KMS instance, the key is a CMK.

    

  • In the KMS console of the new version

    In the left-side navigation pane, click Keys. In the top navigation bar, select a region and select the ID of a KMS instance from the Instance ID drop-down list. All keys in the KMS instance are displayed on the page.

Additional information

The resources that are displayed in the KMS console of the old version are used as an example to describe whether the resources can be migrated.