Dedicated KMS SDK allows you to call the API operations of Dedicated Key Management Service (KMS) in a convenient manner. Dedicated KMS SDK is suitable for business scenarios such as data encryption, data decryption, digital signature generation, and digital signature verification. This topic provides an example on how to use Dedicated KMS SDK for Java to encrypt and decrypt data.

Prerequisites

Make sure that the following requirements are met:
  1. A dedicated KMS instance is created and connected to an HSM cluster. The dedicated KMS instance is in the Connected state. For more information, see Step 2: Configure a dedicated KMS instance.
  2. A symmetric customer master key (CMK) is created for the dedicated KMS instance in the KMS console. The type of the symmetric CMK is Aliyun_AES_256. For more information, see Step 3: Create a CMK for a dedicated KMS instance.
  3. The endpoint of the dedicated KMS instance is obtained. For more information, see Query a dedicated KMS instance.
  4. An Application Access Point (AAP) is created for the dedicated KMS instance, and the client key is obtained. For more information, see Create an AAP.
  5. The CA certificate of the dedicated KMS instance is obtained. For more information, see Obtain a CA certificate of a dedicated KMS instance.

Sample projects

Dedicated KMS SDK provides Maven-based sample projects. You can compile and run the sample projects on local machines. You can also develop applications based on the sample projects. For more information about how to compile and run a project, see alibabacloud-dkms-gcs-java-sdk-example.

Install Dedicated KMS SDK

Add the alibabacloud-dkms-gcs-sdk dependency to your project. Then, your project can automatically download the published Java package of Dedicated KMS SDK from the Maven repository.

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>alibabacloud-dkms-gcs-sdk</artifactId>
  <version>x.x.x</version>
</dependency>
Note The latest version of Dedicated KMS SDK is 0.2.1. For more information about the latest version, see Dedicated KMS SDK for Java.

Configure a CA certificate

To ensure secure communications in the production environment, you must configure a Java-trusted certificate. For more information, see Configure a CA certificate.

In the development environment, you can use the RuntimeOptions command to temporarily ignore the verification of a trusted certificate. Sample code:

import com.aliyun.dkms.gcs.openapi.util.models.RuntimeOptions;

RuntimeOptions runtimeOptions = new RuntimeOptions();
runtimeOptions.setIgnoreSSL(true);
...
client.encryptWithOptions(encryptRequest, runtimeOptions);

Examples of data encryption and decryption

  • Encrypt sensitive data by using a symmetric CMK that is managed by a dedicated KMS instance. The type of the symmetric CMK is Aliyun_AES_256.
    import com.aliyun.dkms.gcs.openapi.models.Config;
    import com.aliyun.dkms.gcs.sdk.Client;
    import com.aliyun.dkms.gcs.sdk.models.*;
    
    // The connection protocol. Set the value to HTTPS. 
    String protocol = "https";
    // The endpoint of the dedicated KMS instance. When you specify this parameter, exclude the scheme https of the endpoint. 
    String endpoint = "<service_id>.cryptoservice.kms.aliyuncs.com";
    // The client key of the dedicated KMS instance. 
    String clientKey = "<your client key>";
    // The password that is used to decrypt the client key of the dedicated KMS instance. 
    String clientKeyPass = "<your client key password>";
    
    Client client = new Client(new Config()
                               .setProtocol(protocol)
                               .setEndpoint(endpoint)
                               .setClientKeyContent(clientKey)
                               .setPassword(clientKeyPass));
    
    // The ID or alias of the symmetric CMK of the dedicated KMS instance. The CMK is used for encryption. 
    String aesCipherKeyId = "<your AES cipher key id>";
    // The data that you want to encrypt. 
    byte[] originData = <your origin data to encrypt>;
    
    EncryptRequest encryptRequest = new EncryptRequest();
    encryptRequest.setKeyId(aesCipherKeyId);
    encryptRequest.setPlaintext(originData);
    
    EncryptResponse encryptResponse = client.encrypt(encryptRequest);
    // The data after encryption. 
    byte[] cipherData = encryptResponse.getCiphertextBlob();
    // The initial vector of Cipher, which is used to decrypt data. 
    byte[] iv = encryptResponse.getIv();
    // The ID of the request. 
    String requestId = encryptResponse.getRequestId();
  • Decrypt ciphermtext by using a symmetric CMK that is managed by a dedicated KMS instance. The type of the symmetric CMK is Aliyun_AES_256.
    // The connection protocol. Set the value to HTTPS. 
    String protocol = "https";
    // The endpoint of the dedicated KMS instance. When you specify this parameter, exclude the scheme https of the endpoint. 
    String endpoint = "<service_id>.cryptoservice.kms.aliyuncs.com";
    // The client key of the dedicated KMS instance. 
    String clientKey = "<your client key>";
    // The password that is used to decrypt the client key of the dedicated KMS instance. 
    String clientKeyPass = "<your client key password>";
    
    Client client = new Client(new Config()
                               .setProtocol(protocol)
                               .setEndpoint(endpoint)
                               .setClientKeyContent(clientKey)
                               .setPassword(clientKeyPass));
    
    // The ID or alias of the symmetric CMK of the dedicated KMS instance. The CMK is used for decryption. 
    String aesCipherKeyId = "<your AES cipher key id>";
    // The data that you want to decrypt. 
    byte[] cipherData = <your cipher data to decrypt>;
    // The initial vector of Cipher, which must be the same as the initial vector that is specified for encryption. 
    byte[] iv = <IV value>;
    
    DecryptRequest decryptRequest = new DecryptRequest();
            decryptRequest.setKeyId(aesCipherKeyId);
            decryptRequest.setCiphertextBlob(cipherData);
            decryptRequest.setIv(iv);
    
    DecryptResponse decryptResponse = client.decrypt(decryptRequest);
    // The raw data. 
    byte[] originData = decryptResponse.getPlaintext();
    // The ID of the request. 
    String requestId = decryptResponse.getRequestId();