How to quickly create a key - Key Management Service - Alibaba Cloud Documentation Center

Key Management Service (KMS) allows you to create keys and use the keys to encrypt and decrypt data in an efficient manner. This helps ensure the security of your data. This topic describes how to create and use a key.

Overview

KMS provides software-protected keys, hardware-protected keys, and default keys to meet your business, security, and compliance requirements. For more information, see Overview of key management and Key types and specifications.

KMS provides default keys free of charge. You can use default keys to perform server-side encryption in Alibaba Cloud services such as Elastic Compute Service (ECS). Default keys support only symmetric decryption. Default keys do not support client-side data encryption.
Software-protected keys support server-side encryption in Alibaba Cloud services, can be used to build application-layer cryptographic solutions, and provide API operations for client-side data encryption and decryption, and signing and verification. Software-protected keys support symmetric keys, asymmetric keys, and key rotation to reduce the risk of key leaks.
Hardware-protected keys support server-side encryption in Alibaba Cloud services, can be used to build application-layer cryptographic solutions, and provide API operations for client-side data encryption and decryption, and signing and verification. Hardware-protected keys support symmetric keys and asymmetric keys and provide more key specifications than software-protected keys. You can store hardware-protected keys in hardware security modules (HSMs) to meet the cryptographic requirements and comply with Federal Information Processing Standards (FIPS). Hardware-protected keys do not support key rotation.

Server-side encryption in Alibaba Cloud services

Keys can be used for server-side encryption in Alibaba Cloud services such as ECS to solve the security risk of plaintext data transmission on the server side. Key types that support this feature are software-protected keys, hardware-protected keys, and default keys.

Example

In this example, the default key of the customer master key (CMK) type is integrated into ECS. For more information about how to integrate Alibaba Cloud services with KMS, see Integration with KMS and Alibaba Cloud services that can be integrated with KMS.

Step 1: Enable the default key of the CMK type

Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.
On the Keys page, click Default Key. Find the default key of the CMK type that you want to enable and click Enable in the Actions column. Set the key name to alias/main.

Note

You can use the default key of the CMK type only for server-side encryption in Alibaba Cloud services, but not for client-side data encryption. If you want to implement client-side data encryption, create an instance and then create a software-protected key or a hardware-protected key.

Step 2: Integrate the default key of KMS into ECS

When you purchase an ECS instance on the buy page, select the default key named alias/main to enable server-side encryption.

Step 3: Use KMS to encrypt data in ECS for ciphertext transmission

When data is transferred to ECS, ECS calls the API operations of KMS to encrypt and decrypt the data. You do not need to manually process the data. In most cases, Alibaba Cloud services use envelope encryption to encrypt data. For more information, see Use envelope encryption.

Application-layer cryptographic solutions

Keys can be used to build application-layer cryptographic solutions and provide API operations for client-side data encryption and decryption, and signing and verification. Key types that support this feature are software-protected keys and hardware-protected keys.

Prerequisites

A KMS instance of the hardware key management type or the software key management type is purchased and enabled. For more information, see Purchase and enable a KMS instance.

Example

In this example, a key of a KMS instance of the software key management type is used to encrypt (Encrypt) and decrypt (Decrypt) application-layer data. For more information, see Use a key to encrypt and decrypt data.

Step 1: Create a software-protected key

Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Keys.
On the Keys tab, click Create Key and complete the configurations as prompted.

KMS Instance: Select the purchased KMS instance
Key Type: Select Symmetric Key.
Key Specifications: Select Aliyun_AES_256.

Step 2: Install dependencies

Make preparations.
Environment requirements
Java Development Kit (JDK) 8 or later is downloaded and installed.
Java version
Run the java -version command on the terminal to check the JDK version.

Install Alibaba Cloud SDK.

Add the following Maven dependency to your project. Then, a Java package of Alibaba Cloud SDK is automatically downloaded from the Maven repository. Make sure that Alibaba Cloud SDK V2.0 is used.

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>kms20160120</artifactId>
  <version>1.2.3</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>tea</artifactId>
    <version>1.3.2</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>tea-openapi</artifactId>
    <version>0.3.6</version>
</dependency>

Step 3: Create a credential

Alibaba Cloud SDK supports multiple Resource Access Management (RAM)-based authentication methods. In this example, AccessKey pairs of RAM users are used. For more information about authentication methods, see Manage access credentials.

Create an AccessKey pair for a RAM user in the RAM console. For more information, see Create an AccessKey pair.
If an AccessKey pair is already created for the RAM user, skip this step.
Grant the required permissions to the RAM user.
For example, if the RAM user requires the permissions to perform cryptographic operations, you can attach the system policy AliyunKMSCryptoUserAccess to the RAM user. For more information, see Grant permissions to a RAM user.
Note
KMS provides the following permission configuration methods:
- Identity-based policies: The policy in the preceding example is an identity-based policy. Identity-based policies associate identities with corresponding permissions to implement access control. For more information, see Use RAM to implement access control.
- Resource-based policies: Resource-based policies include key and secret policies. Such policies are directly associated with resources and are used to define access rules for specific resources. For more information, see Key policies and Secret policies.

Step 4: Obtain the certificate authority (CA) certificate of the KMS instance

Log on to the KMS console. In the top navigation bar, select a region. In the left-side navigation pane, choose Resource > Instances.
In the upper part of the page that appears, click Instance CA Certificate.

Step 5: Obtain the Virtual Private Cloud (VPC) endpoint of the instance

Obtain the VPC endpoint of the instance on the instance details page.

Step 6: Call API operations

Initialize Alibaba Cloud SDK.

Important

Make sure that Alibaba Cloud SDK V2.0 is used. You must set the config.endpoint parameter to the VPC endpoint of the instance and configure the CA certificate of the instance.

    public static com.aliyun.kms20160120.Client createClient() throws Exception {
        // If the project code is leaked, the AccessKey pair may be leaked and the security of all resources within your account may be compromised. The following sample code is for reference only.
        // We recommend that you use Security Token Service (STS) tokens to enhance security. For more information about authentication methods, visit https://www.alibabacloud.com/help/en/sdk/developer-reference/v2-manage-access-credentials?spm=a2c63.p38356.help-menu-262060.d_1_4_1_2.1ad47c23arIlrq.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // Required. Make sure that the environment variable ALIBABA_CLOUD_ACCESS_KEY_ID is configured.
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. Make sure that the environment variable ALIBABA_CLOUD_ACCESS_KEY_SECRET is configured.
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Enter the VPC endpoint of the instance. Example: kst-hzz65f176a0ogplgq****.cryptoservice.kms.aliyuncs.com.
        config.endpoint = "<VPC endpoint of the instance>";
        // Enter the content of the CA certificate of the instance.
        config.ca = "<CA certificate of the instance>";
        return new com.aliyun.kms20160120.Client(config);
    }

Call the Encrypt operation to encrypt data.

package com.aliyun.sample;

import com.aliyun.tea.*;

public class Sample {
  public static com.aliyun.kms20160120.Client createClient() throws Exception {
        // If the project code is leaked, the AccessKey pair may be leaked and the security of all resources within your account may be compromised. The following sample code is for reference only.
        // We recommend that you use STS tokens to enhance security. For more information about authentication methods, visit https://www.alibabacloud.com/help/en/sdk/developer-reference/v2-manage-access-credentials?spm=a2c63.p38356.help-menu-262060.d_1_4_1_2.1ad47c23arIlrq.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // Required. Make sure that the environment variable ALIBABA_CLOUD_ACCESS_KEY_ID is configured.
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. Make sure that the environment variable ALIBABA_CLOUD_ACCESS_KEY_SECRET is configured.
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Enter the VPC endpoint of the instance. Example: kst-hzz65f176a0ogplgq****.cryptoservice.kms.aliyuncs.com.
        config.endpoint = "<VPC endpoint of the instance>";
        // Enter the content of the CA certificate of the instance.
        config.ca = "<CA certificate of the instance>";
        return new com.aliyun.kms20160120.Client(config);
    }
   
     public static void main(String[] args_) throws Exception {
        java.util.List<String> args = java.util.Arrays.asList(args_);
        com.aliyun.kms20160120.Client client = Sample.createClient();
        com.aliyun.kms20160120.models.EncryptRequest encryptRequest = new com.aliyun.kms20160120.models.EncryptRequest()
                .setKeyId("<keyID>")
                .setPlaintext("<PlaintText>");
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            // Run the sample code to obtain the return value of the API operation.
            client.encryptWithOptions(encryptRequest, runtime);
        } catch (TeaException error) {
            // Handle exceptions with caution in actual business scenarios and do not ignore the exceptions in your project. In this example, exceptions are provided for reference only.
            // The error message.
            System.out.println(error.getMessage());
            // The URL for troubleshooting.
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (Exception _error) {
            TeaException error = new TeaException(_error.getMessage(), _error);
            // Handle exceptions with caution in actual business scenarios and do not ignore the exceptions in your project. In this example, exceptions are provided for reference only.
            // The error message.
            System.out.println(error.getMessage());
            // The URL for troubleshooting.
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }        
    }
}

Call the Decrypt operation to decrypt data.

package com.aliyun.sample;

import com.aliyun.tea.*;

public class Sample {

    public static com.aliyun.kms20160120.Client createClient() throws Exception {
        // If the project code is leaked, the AccessKey pair may be leaked and the security of all resources within your account may be compromised. The following sample code is for reference only.
        // We recommend that you use STS tokens to enhance security. For more information about authentication methods, visit https://www.alibabacloud.com/help/en/sdk/developer-reference/v2-manage-access-credentials?spm=a2c63.p38356.help-menu-262060.d_1_4_1_2.1ad47c23arIlrq.
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // Required. Make sure that the environment variable ALIBABA_CLOUD_ACCESS_KEY_ID is configured.
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                // Required. Make sure that the environment variable ALIBABA_CLOUD_ACCESS_KEY_SECRET is configured.
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Enter the VPC endpoint of the instance. Example: kst-hzz65f176a0ogplgq****.cryptoservice.kms.aliyuncs.com.
        config.endpoint = "<VPC endpoint of the instance>";
        // Enter the content of the CA certificate of the instance.
        config.ca = "<CA certificate of the instance>";
        return new com.aliyun.kms20160120.Client(config);
    }

    public static void main(String[] args_) throws Exception {
        java.util.List<String> args = java.util.Arrays.asList(args_);
        com.aliyun.kms20160120.Client client = Sample.createClient();
        com.aliyun.kms20160120.models.DecryptRequest decryptRequest = new com.aliyun.kms20160120.models.DecryptRequest()
                .setCiphertextBlob("<CiphertextBlob>");
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        try {
            // Run the sample code to obtain the return value of the API operation.
            client.decryptWithOptions(decryptRequest, runtime);
        } catch (TeaException error) {
            // Handle exceptions with caution in actual business scenarios and do not ignore the exceptions in your project. In this example, exceptions are provided for reference only.
            // The error message.
            System.out.println(error.getMessage());
            // The URL for troubleshooting.
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (Exception _error) {
            TeaException error = new TeaException(_error.getMessage(), _error);
            // Handle exceptions with caution in actual business scenarios and do not ignore the exceptions in your project. In this example, exceptions are provided for reference only.
            // The error message.
            System.out.println(error.getMessage());
            // The URL for troubleshooting.
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }        
    }
}

References

For more information about scenarios, algorithms, and specifications of keys, see Overview of key management.
For more information about SDK integration, see Alibaba Cloud SDK (Java).
If you want to encrypt and decrypt a small amount of data, you can use a key to encrypt and decrypt the data. For more information, see Use a key to encrypt and decrypt data.
If you want to encrypt and decrypt a large amount of data, you can use envelope encryption. For more information, see Use envelope encryption.