专属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();