KMS实例SDK for Java

前提条件

• 已购买和启用KMS实例。具体操作，请参见购买和启用KMS实例。

• 已完成密钥和凭据的创建。具体操作，请参见软件密钥、硬件密钥、创建凭据。

  说明

  如果您的业务不涉及凭据，则无需创建凭据。

• 已创建应用接入点并保存了Client Key、获取KMS实例CA证书。具体操作，请参见通过应用接入点访问KMS实例。

• 请确保应用程序运行环境可访问KMS实例VPC地址。

  业务场景	说明
  应用程序运行环境和KMS实例在同一个地域，且属于同一个VPC	默认应用程序运行环境和KMS实例间网络互通，您无需配置。
  应用程序运行环境和KMS实例在同一个地域，但属于不同VPC	您需要配置多个VPC访问同一个KMS实例，具体操作，请参见同地域多VPC访问KMS实例。
  应用程序运行环境和KMS实例在不同地域	您需要配置应用跨地域访问KMS实例。具体操作，请参见应用跨地域访问KMS实例。

添加SDK依赖

在项目中添加Maven依赖，从Maven仓库中自动下载Java安装包。

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>alibabacloud-dkms-gcs-sdk</artifactId>
  <version>xx.xx.xx</version>
</dependency>
<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>tea</artifactId>
    <version>[1.2.3)</version>
</dependency>
            

初始化SDK

使用Java SDK发起KMS实例API请求，您需要初始化一个Client实例。

import com.aliyun.dkms.gcs.openapi.models.Config;
import com.aliyun.dkms.gcs.sdk.Client;

// 连接协议请设置为"https"。KMS实例服务仅允许通过HTTPS协议访问。
String protocol = "https";
// 设置endpoint为<your KMS Instance Id>.cryptoservice.kms.aliyuncs.com。
String endpoint = "<your KMS Instance Id>.cryptoservice.kms.aliyuncs.com";

// Client Key。
String clientKeyFilePath = "<your client key file path>";
//String clientKey = "<your client key>";

// Client Key口令。
String clientKeyPass = "<your client key password>";

// KMS实例的CA证书，可通过文件路径或直接设置内容。
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));

使用已初始化的Client调用KMS实例API

初始化Client后，您可以通过Client调用KMS实例API，本文介绍如下几个使用场景和代码示例。关于KMS实例API的详细信息，请参见实例API概览。

• 调用Encrypt接口使用对称密钥加密数据

  详细代码示例，请参见原始代码。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  //密钥的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();

• 调用Decrypt接口使用对称密钥解密密文

  详细代码示例，请参见原始代码。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  //密钥的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();

• 调用Sign接口使用非对称密钥进行数字签名

  详细代码示例，请参见原始代码。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  //密钥的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();

• 调用Verify接口使用非对称密钥验证数字签名

  详细代码示例，请参见原始代码。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  //密钥的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();

• 调用GetSecretValue接口获取凭据值

  详细代码示例，请参见原始代码。

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