专属KMS Java SDK - 密钥管理服务

背景信息

您可以访问开源代码仓库，查看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的默认配置项。

配置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);
```

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