全部產品
Search
文件中心

Key Management Service:專屬KMS Java SDK

更新時間:Jul 06, 2024

專屬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();