Key Management Service:KMS Instance SDK for Java

Prerequisites

• A KMS instance is purchased and enabled. For more information, see Purchase and enable a KMS instance.

• A key and a secret are created. For more information, see Software-protected keys, Hardware-protected keys, and Create a secret.

  Note

  If your business does not require a secret, you do not need to create a secret.

• An application access point (AAP) is created, the client key that is bound to the AAP is saved, and a certificate authority (CA) certificate is obtained for the KMS instance. For more information, see Access a KMS instance by using an AAP.

• Make sure that the application runtime environment and the VPC of the KMS instance can communicate with each other.

  Business scenario	Description
  The application runtime environment and the KMS instance reside in the same region and belong to the same VPC.	By default, the application runtime environment and the KMS instance can communicate with each other. No manual configuration is required.
  The application runtime environment and the KMS instance reside in the same region but belong to different VPCs.	You must configure multiple VPCs to access the same KMS instance. For more information, see Access a KMS instance from multiple VPCs in the same region.

Add a dependency

Add a Maven dependency to your project. Then, a Java package of KMS Instance SDK is automatically downloaded from the Maven repository.

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>alibabacloud-dkms-gcs-sdk</artifactId>
  <version>xx.xx.xx</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>tea</artifactId>
    <version>[1.2.3)</version>
</dependency>
            

Initialize KMS Instance SDK for Java

To use KMS Instance SDK for Java to initiate an API request, you must create a client.

import com.aliyun.dkms.gcs.openapi.models.Config;
import com.aliyun.dkms.gcs.sdk.Client;

// The connection protocol. Set the value to https. KMS supports connections only over HTTPS. 
String protocol = "https";
// The endpoint of your KMS instance. Set the value in the following format: <ID of your KMS instance >.cryptoservice.kms.aliyuncs.com. 
String endpoint = "<your KMS Instance Id>.cryptoservice.kms.aliyuncs.com";

// The client key. 
String clientKeyFilePath = "<your client key file path>";
//String clientKey = "<your client key>";

// The password of the client key file. 
String clientKeyPass = "<your client key password>";

// The certificate authority (CA) certificate of the KMS instance. You can specify the path to the CA certificate file or enter the content of the CA certificate. 
String caCertPath = "<path/to/DKMSInstanceCACertificates>";
//String caCert = "<The DKMS instance CA certificates content>";

Client client = new Client(new Config()
                           .setProtocol(protocol)
                           .setEndpoint(endpoint)
                           .setCaFilePath(caCertPath) // The path to the CA certificate file or the content of the CA certificate. Configure this parameter based on your business requirements. 
                           //.setCa(caCert) // The content of the CA certificate. 
                           .setClientKeyFile(clientKeyFilePath)// The path to the client key file or the content of the client key file. Configure this parameter based on your business requirements. 
                           //.setClientKeyContent(clientKey)// The content of the client key file. 
                           .setPassword(clientKeyPass));

Use the client to call an operation

After you create a client, you can use the client to call KMS Instance API operations. The following sample code provides examples on how to call operations in different scenarios: For more information about KMS Instance API operations, see List of operations by function.

• Call the Encrypt operation to encrypt data by using a symmetric key

  For more information about the sample code, see Source code.

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  // The ID or alias of the key. 
  String cipherKeyId = "<your cipher key id>";
  // The data that you want to encrypt. 
  byte[] originData = <your origin data to encrypt>;
  
  EncryptRequest encryptRequest = new EncryptRequest();
  encryptRequest.setKeyId(cipherKeyId);
  encryptRequest.setPlaintext(originData);
  
  EncryptResponse encryptResponse = client.encrypt(encryptRequest);
  // The ciphertext. 
  byte[] cipherData = encryptResponse.getCiphertextBlob();
  // The initial vector of Cipher that is used to decrypt data. 
  byte[] iv = encryptResponse.getIv();
  // The request ID. 
  String requestId = encryptResponse.getRequestId();

• Call the Decrypt operation to decrypt data by using a symmetric key

  For more information about the sample code, see Source code.

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  // The ID or alias of the key. 
  String cipherKeyId = "<your cipher key id>";
  // The ciphertext that you want to decrypt. 
  byte[] cipherData = <your cipher data to decrypt>;
  // The initial vector of Cipher. The initial vector must be the same as the initial vector that is specified for encryption. 
  byte[] iv = <IV value>;
  
  DecryptRequest decryptRequest = new DecryptRequest();
          decryptRequest.setKeyId(cipherKeyId);
          decryptRequest.setCiphertextBlob(cipherData);
          decryptRequest.setIv(iv);
  
  DecryptResponse decryptResponse = client.decrypt(decryptRequest);
  // The plaintext. 
  byte[] originData = decryptResponse.getPlaintext();
  // The request ID. 
  String requestId = decryptResponse.getRequestId();

• Call the Sign operation to sign data by using an asymmetric key

  For more information about the sample code, see Source code.

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  // The ID or alias of the key. 
  String signerKeyId = "<the signer key id>";
  // The data to sign. 
  byte[] message = <the data to sign>;
  
  SignRequest signRequest = new SignRequest();
  signRequest.setKeyId(signKeyId);
  signRequest.setMessage(message);
  
  SignResponse signResponse = client.sign(signRequest);
  // The signature value. 
  byte[] signature = signResponse.getSignature();
  // The request ID. 
  String requestId = signResponse.getRequestId();

• Call the Verify operation to verify a digital signature by using an asymmetric key

  For more information about the sample code, see Source code.

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  // The ID or alias of the key. 
  String signerKeyId = "<the signer key id>";
  // The data for which you want to verify the digital signature. 
  byte[] message = <the data to sign>;
  
  VerifyRequest verifyRequest = new VerifyRequest();
  verifyRequest.setKeyId(signerKeyId);
  verifyRequest.setMessage(message);
  verifyRequest.setSignature(signature);
  
  VerifyResponse verifyResponse = client.verify(verifyRequest);
  // The verification result. 
  boolean valid = verifyResponse.getValue();
  // The request ID. 
  String requestId = verifyResponse.getRequestId();

• Call the GetSecretValue operation to retrieve a secret value

  For more information about the sample code, see Source code.

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  // The secret name. 
  String secretName = "<your-secret-name>";
  
  GetSecretValueRequest request = new GetSecretValueRequest()
                  .setSecretName(secretName);
  
  GetSecretValueResponse getSecretValueResponse = client.getSecretValue(request);
  // The secret value.
  String secretData = getSecretValueResponse.getSecretData();
  // The request ID.
  String requestId = getSecretValueResponse.getRequestId();