專屬KMS SDK for Java幫助您通過簡單的編程訪問專屬KMS的API，實現加密解密、簽名驗簽和獲取憑據信息的業務訴求。本文介紹如何初始化SDK以及如何調用接口進行加密解密、簽名驗簽和獲取憑據信息。

背景信息

您可以訪問開源代碼倉庫，查看SDK源碼及代碼示例。同時也歡迎您提出寶貴意見，或者提供代碼示例。

前提條件

  • 您已經啟用專屬KMS實例并正常連接密碼機，為實例創建密鑰及應用接入點，并保存了Client Key及CA證書。具體操作，請參見快速入門。
    說明 CA證書下載后文件名默認為PrivateKmsCA_kst-******.pem，應用身份憑證文件下載后文件名默認為ClientKey_******.json。
  • 已經獲取專屬KMS實例VPC地址，并確保可以通過以下方式訪問專屬KMS實例VPC地址：
    • 在激活密碼機實例集群時設置的VPC中訪問專屬KMS實例VPC地址。
    • 本地設備所在網絡可以正常解析并訪問專屬KMS實例VPC地址。

    具體操作，請參見查詢專屬KMS標準版實例。

安裝SDK

在項目中添加alibabacloud-dkms-gcs-sdk的依賴，可從Maven倉庫中自動下載發布的Java安裝包。

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>alibabacloud-dkms-gcs-sdk</artifactId>
  <version>x.x.x</version>
</dependency>
說明 專屬KMS SDK的最新版本，請參見專屬KMS SDK for Java。

初始化SDK

您可以初始化一個專屬KMS實例的Java客戶端，用于調用專屬KMS實例提供的服務：使用密鑰進行密碼計算、獲取憑據值等。使用Java SDK發起專屬KMS API請求，您需要初始化一個Client實例。

適用于0.2.7及以上版本（推薦）

初始化Client實例。
import com.aliyun.dkms.gcs.openapi.models.Config;
import com.aliyun.dkms.gcs.sdk.Client;

// 專屬KMS實例與客戶端之間的連接協議，固定為https
String protocol = "https";
// Endpoint，專屬KMS實例VPC地址去掉https://
String endpoint = "<service_id>.cryptoservice.kms.aliyuncs.com";

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

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

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));
開發環境可使用RuntimeOptions設置臨時忽略可信證書的驗證。示例代碼如下：
import com.aliyun.dkms.gcs.openapi.util.models.RuntimeOptions;

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

適用于0.2.6及以下版本

  1. 配置CA證書。
    為保障生產環境通信安全，需要配置Java可信證書。
    1. 將CA證書文件拆分為2個證書文件。
      CA證書文件內容有兩部分，均以 ------BEGIN CERTIFICATE --------開頭，以------END CERTIFICATE -------- 結尾。默認第一部分為rootca.pem的內容，第二部分為subca.pem的內容。
      • 文件1：rootca.pem
        -----BEGIN CERTIFICATE-----
<Root CA Certificate BASE64 Content>
-----END CERTIFICATE-----
      • 文件2：subca.pem
        -----BEGIN CERTIFICATE-----
<Sub CA Certificate BASE64 Content>
-----END CERTIFICATE-----
    2. 使用keytool工具將拆分后的CA證書導入至JAVA_HOME/jre/lib/security/cacerts。
      • 導入文件1（rootca.pem）
        keytool -importcert -alias PrivateKmsCA_RootCA -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file rootca.pem
      • 導入文件2（subca.pem）
        keytool -importcert -alias PrivateKmsCA_SubCA -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file subca.pem
    3. 驗證代碼。
      URL serviceUrl = new URL("https://<service_id>.cryptoservice.kms.aliyuncs.com");
serviceUrl.openConnection().connect();
      說明 如果沒有javax.net.ssl.SSLHandshakeException的異常提示，則配置正確。
      開發環境可使用RuntimeOptions設置臨時忽略可信證書的驗證。示例代碼如下：
      import com.aliyun.dkms.gcs.openapi.util.models.RuntimeOptions;

RuntimeOptions runtimeOptions = new RuntimeOptions();
runtimeOptions.setIgnoreSSL(true);
...
client.encryptWithOptions(encryptRequest, runtimeOptions);
  2. 創建專屬KMS的Client。
    import com.aliyun.dkms.gcs.openapi.models.Config;
import com.aliyun.dkms.gcs.sdk.Client;

//專屬KMS實例與客戶端之間的連接協議，固定為https。
String protocol = "https";
//Endpoint，專屬KMS實例服務地址去掉https://。
String endpoint = "<service_id>.cryptoservice.kms.aliyuncs.com";
//專屬KMS實例Client Key。
String clientKey = "<your client key>";
//專屬KMS實例Client Key解密口令。
String clientKeyPass = "<your client key password>";

Client client = new Client(new Config()
                           .setProtocol(protocol)
                           .setEndpoint(endpoint)
                           .setClientKeyContent(clientKey)
                           .setPassword(clientKeyPass));

代碼示例

  • 專屬KMS Client調用Encrypt接口使用對稱密鑰加密數據

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

    import com.aliyun.dkms.gcs.sdk.Client;
import com.aliyun.dkms.gcs.sdk.models.*;

//專屬KMS實例加密密鑰的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()；
  • 專屬KMS Client調用Decrypt接口使用對稱密鑰解密密文

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

    import com.aliyun.dkms.gcs.sdk.Client;
import com.aliyun.dkms.gcs.sdk.models.*;

//專屬KMS實例解密密鑰的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();
  • 專屬KMS Client調用Sign接口使用非對稱密鑰進行數字簽名

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

    import com.aliyun.dkms.gcs.sdk.Client;
import com.aliyun.dkms.gcs.sdk.models.*;

//專屬KMS實例簽名密鑰的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();
  • 專屬KMS Client調用Verify接口使用非對稱密鑰驗證數字簽名

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

    import com.aliyun.dkms.gcs.sdk.Client;
import com.aliyun.dkms.gcs.sdk.models.*;

//專屬KMS實例簽名密鑰的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();
  • 使用專屬KMS Client調用GetSecretValue接口獲取憑據值

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

    說明 0.2.6及以上版本的專屬KMS Java SDK才支持獲取憑據值。 
    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();