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

背景信息

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

前提条件

  • 您已经启用专属KMS标准版实例并正常连接密码机,为实例创建密钥及应用接入点,并保存了Client Key及CA证书。具体操作,请参见快速入门
  • 已经获取专属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实例,并根据需要修改Config的默认配置项。

  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/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
    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。

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