前提條件

• 已購買和啟用KMS實例。具體操作，請參見購買和啟用KMS實例。

• 已完成密鑰和憑據的創建。具體操作，請參見軟件密鑰、硬件密鑰、創建憑據。

  說明

  如果您的業務不涉及憑據，則無需創建憑據。

• 已創建應用接入點并保存了Client Key、獲取KMS實例CA證書。具體操作，請參見通過應用接入點訪問KMS實例。

• 請確保應用程序運行環境可訪問KMS實例VPC地址。

  業務場景	說明
  應用程序運行環境和KMS實例在同一個地域，且屬于同一個VPC	默認應用程序運行環境和KMS實例間網絡互通，您無需配置。
  應用程序運行環境和KMS實例在同一個地域，但屬于不同VPC	您需要配置多個VPC訪問同一個KMS實例，具體操作，請參見同地域多VPC訪問KMS實例。
  應用程序運行環境和KMS實例在不同地域	您需要配置應用跨地域訪問KMS實例。具體操作，請參見應用跨地域訪問KMS實例。

添加SDK依賴

在項目中添加Maven依賴，從Maven倉庫中自動下載Java安裝包。

<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>
            

初始化SDK

使用Java SDK發起KMS實例API請求，您需要初始化一個Client實例。

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

// 連接協議請設置為"https"。KMS實例服務僅允許通過HTTPS協議訪問。
String protocol = "https";
// 設置endpoint為<your KMS Instance Id>.cryptoservice.kms.aliyuncs.com。
String endpoint = "<your KMS Instance Id>.cryptoservice.kms.aliyuncs.com";

// Client Key。
String clientKeyFilePath = "<your client key file path>";
//String clientKey = "<your client key>";

// Client Key口令。
String clientKeyPass = "<your client key password>";

// KMS實例的CA證書，可通過文件路徑或直接設置內容。
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) // 設置CA證書文件路徑，還支持設置CA證書內容，請根據需要選擇。
                           //.setCa(caCert) // 設置CA證書內容。
                           .setClientKeyFile(clientKeyFilePath)//設置應用身份憑證文件路徑，還支持設置應用身份憑證內容，請根據需要選擇。
                           //.setClientKeyContent(clientKey)//設置應用身份憑證內容。
                           .setPassword(clientKeyPass));

使用已初始化的Client調用KMS實例API

初始化Client后，您可以通過Client調用KMS實例API，本文介紹如下幾個使用場景和代碼示例。關于KMS實例API的詳細信息，請參見實例API概覽。

• 調用Encrypt接口使用對稱密鑰加密數據

  詳細代碼示例，請參見原始代碼。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  //密鑰的ID或別名（Alias）。
  String cipherKeyId = "<your cipher key id>";
  //待加密數據。
  byte[] originData = <your origin data to encrypt>;
  
  EncryptRequest encryptRequest = new EncryptRequest();
  encryptRequest.setKeyId(cipherKeyId);
  encryptRequest.setPlaintext(originData);
  
  EncryptResponse encryptResponse = client.encrypt(encryptRequest);
  //加密數據。
  byte[] cipherData = encryptResponse.getCiphertextBlob();
  //Cipher初始向量，用于解密數據。
  byte[] iv = encryptResponse.getIv();
  //請求ID。
  String requestId = encryptResponse.getRequestId();

• 調用Decrypt接口使用對稱密鑰解密密文

  詳細代碼示例，請參見原始代碼。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  //密鑰的ID或別名（Alias）。
  String cipherKeyId = "<your cipher key id>";
  //待解密數據。
  byte[] cipherData = <your cipher data to decrypt>;
  //Cipher初始向量，必須與加密時一致。
  byte[] iv = <IV value>;
  
  DecryptRequest decryptRequest = new DecryptRequest();
          decryptRequest.setKeyId(cipherKeyId);
          decryptRequest.setCiphertextBlob(cipherData);
          decryptRequest.setIv(iv);
  
  DecryptResponse decryptResponse = client.decrypt(decryptRequest);
  //原始數據。
  byte[] originData = decryptResponse.getPlaintext();
  //請求ID。
  String requestId = decryptResponse.getRequestId();

• 調用Sign接口使用非對稱密鑰進行數字簽名

  詳細代碼示例，請參見原始代碼。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  //密鑰的ID或別名（Alias）。
  String signerKeyId = "<the signer key id>";
  //待簽名數據。
  byte[] message = <the data to sign>;
  
  SignRequest signRequest = new SignRequest();
  signRequest.setKeyId(signKeyId);
  signRequest.setMessage(message);
  
  SignResponse signResponse = client.sign(signRequest);
  //簽名值。
  byte[] signature = signResponse.getSignature();
  //請求ID。
  String requestId = signResponse.getRequestId();

• 調用Verify接口使用非對稱密鑰驗證數字簽名

  詳細代碼示例，請參見原始代碼。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  //密鑰的ID或別名（Alias）。
  String signerKeyId = "<the signer key id>";
  //待驗證簽名的數據。
  byte[] message = <the data to sign>;
  
  VerifyRequest verifyRequest = new VerifyRequest();
  verifyRequest.setKeyId(signerKeyId);
  verifyRequest.setMessage(message);
  verifyRequest.setSignature(signature);
  
  VerifyResponse verifyResponse = client.verify(verifyRequest);
  //驗簽結果。
  boolean valid = verifyResponse.getValue();
  //請求ID。
  String requestId = verifyResponse.getRequestId();

• 調用GetSecretValue接口獲取憑據值

  詳細代碼示例，請參見原始代碼。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  //KMS的憑據名稱。
  String secretName = "<your-secret-name>";
  
  GetSecretValueRequest request = new GetSecretValueRequest()
                  .setSecretName(secretName);
  
  GetSecretValueResponse getSecretValueResponse = client.getSecretValue(request);
  //憑據值
  String secretData = getSecretValueResponse.getSecretData();
  //請求ID
  String requestId = getSecretValueResponse.getRequestId();