专属KMS SDK for Java帮助您通过简单的编程访问专属KMS的API,实现加密解密、签名验签的业务诉求。

前提条件

请确保您已经完成以下操作:
  1. 已经创建专属KMS实例并正常连接密码机,专属KMS实例状态为已连接。具体操作,请参见步骤二:配置专属KMS实例
  2. 已经通过密钥管理控制台为专属KMS实例创建密钥。具体操作,请参见步骤三:为专属KMS实例创建密钥

背景信息

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

安装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当前版本为0.2.0。最新版本,请参见专属KMS SDK for Java

初始化SDK

您可以初始化一个专属KMS实例的Java客户端,用于调用专属KMS实例管理的密钥等资源。使用Java SDK发起专属KMS API请求,您需要初始化一个Client实例,并根据需要修改Config的默认配置项。

  1. 配置CA证书。

    为保障生产环境通信安全,需要配置Java可信证书。具体配置过程如下:

    1. 获取专属KMS实例CA证书。

      具体操作,请参见获取专属KMS实例CA证书

      文件名为PrivateKmsCA_kst-xxxxxx.pem,文件内容示例如下:

      -----BEGIN CERTIFICATE-----
      <Root CA Certificate BASE64 Content>
      -----END CERTIFICATE-----
      -----BEGIN CERTIFICATE-----
      <Sub CA Certificate BASE64 Content>
      -----END CERTIFICATE-----
    2. 确定Java安装路径JAVA_HOME
    3. 将下载的CA证书文件拆分为2个证书文件。
      • 文件1:rootca.pem
        -----BEGIN CERTIFICATE-----
        <Root CA Certificate BASE64 Content>
        -----END CERTIFICATE-----
      • 文件2:subca.pem
        -----BEGIN CERTIFICATE-----
        <Sub CA Certificate BASE64 Content>
        -----END CERTIFICATE-----
    4. 使用keytool工具导入CA证书至JAVA_HOME/lib/security/cacerts文件。
      • 导入文件1(rootca.pem
        keytool -importcert -alias PrivateKmsCA_RootCA -keystore cacerts -storepass changeit -file rootca.pem
      • 导入文件2(subca.pem
        keytool -importcert -alias PrivateKmsCA_SubCA -keystore cacerts -storepass changeit -file subca.pem
    5. 验证代码。
      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。

    创建专属KMS实例Client时,需要指定实例的Endpoint。EndPoint为专属KMS实例服务地址去掉HTTPS。关于专属KMS实例服务地址的更多信息,请参见查询专属KMS实例

    import com.aliyun.dkms.gcs.openapi.models.Config;
    import com.aliyun.dkms.gcs.sdk.Client;
    
    // 连接协议,固定为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);
    // 原始数据。
    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[] digest = <the digest or ZA-Value of the data to sign>;
    
    SignRequest signRequest = new SignRequest();
    signRequest.setKeyId(signKeyId);
    
    signRequest.setDigest(digest);
    
    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[] digest = <the digest or sm2-signature-pretreatment-value of the plaintext to sign>;
    
    VerifyRequest verifyRequest = new VerifyRequest();
    verifyRequest.setKeyId(signerKeyId);
    verifyRequest.setDigest(digest);
    verifyRequest.setSignature(signature);
    
    VerifyResponse verifyResponse = client.verify(verifyRequest);
    // 验签结果。
    boolean valid = verifyResponse.getValue();
    // 请求ID。
    String requestId = verifyResponse.getRequestId();