专属KMS SDK for Java帮助您通过简单的编程访问专属KMS的API,实现加密解密、签名验签和获取凭据信息的业务诉求。本文介绍如何初始化SDK以及如何调用接口进行加密解密、签名验签和获取凭据信息。

背景信息

您可以访问开源代码仓库,查看SDK源码及代码示例。同时也欢迎您提出宝贵意见,或者提供代码示例。

前提条件

  • 您已经启用专属KMS基础版实例,为实例创建密钥及应用接入点,并保存了Client Key及CA证书。具体操作,请参见快速入门
    说明 CA证书下载后文件名默认为PrivateKmsCA_kst-******.pem,应用身份凭证文件下载后文件名默认为ClientKey_******.json。
  • 您已经获取了专属KMS基础版实例VPC地址,并确保可以通过以下方式访问专属KMS基础版实例VPC地址:
    • 启用专属KMS基础版实例时设置了VPC ID,在该VPC中您可以访问专属KMS基础版实例VPC地址。
    • 您专属KMS SDK程序所在环境的网络,可以正常解析并访问专属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();