Key Management Service:Dedicated KMS SDK for Java

SDK 0.2.7 and later (recommended)

Pass the CA certificate and client key as file paths or inline content — choose one approach based on your deployment environment.

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

// Connection protocol. Must be https.
String protocol = "https";
// VPC endpoint of the dedicated KMS instance (exclude the https:// scheme).
String endpoint = "<service_id>.cryptoservice.kms.aliyuncs.com";

// Path to the client key file, or the client key content directly.
String clientKeyFilePath = "<path/to/ClientKey_******.json>";
// String clientKey = "<client key content>";

// Password used to decrypt the client key.
String clientKeyPass = "<your client key password>";

// Path to the CA certificate file, or the certificate content directly.
String caCertPath = "<path/to/PrivateKmsCA_kst-******.pem>";
// String caCert = "<CA certificate content>";

Client client = new Client(new Config()
    .setProtocol(protocol)
    .setEndpoint(endpoint)
    .setCaFilePath(caCertPath)          // Use setCa(caCert) to pass certificate content instead.
    .setClientKeyFile(clientKeyFilePath) // Use setClientKeyContent(clientKey) to pass key content instead.
    .setPassword(clientKeyPass));

Bypassing SSL verification in development

In a development environment, use RuntimeOptions to skip trusted certificate verification. Do not use this in production.

import com.aliyun.dkms.gcs.openapi.util.models.RuntimeOptions;

RuntimeOptions runtimeOptions = new RuntimeOptions();
runtimeOptions.setIgnoreSSL(true);

client.encryptWithOptions(encryptRequest, runtimeOptions);

SDK 0.2.6 and earlier

For older SDK versions, import the CA certificate into the Java trust store manually before creating the client.

Step 1: Split the CA certificate into two files

The CA certificate file contains two certificates, each delimited by ------BEGIN CERTIFICATE -------- and ------END CERTIFICATE --------. Split them into separate files:

• rootca.pem — the first certificate (root CA)

  ------BEGIN CERTIFICATE --------
  <Root CA Certificate BASE64 Content>
  ------END CERTIFICATE --------

• subca.pem — the second certificate (subordinate CA)

  ------BEGIN CERTIFICATE --------
  <Sub CA Certificate BASE64 Content>
  ------END CERTIFICATE --------

Step 2: Import both files into the Java trust store

keytool -importcert -alias PrivateKmsCA_RootCA -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file rootca.pem

keytool -importcert -alias PrivateKmsCA_SubCA -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file subca.pem

Step 3: Verify the connection

URL serviceUrl = new URL("https://<service_id>.cryptoservice.kms.aliyuncs.com");
serviceUrl.openConnection().connect();

If no javax.net.ssl.SSLHandshakeException is thrown, the certificate is correctly configured.

Step 4: Create the client

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

String protocol = "https";
String endpoint = "<service_id>.cryptoservice.kms.aliyuncs.com";
String clientKey = "<your client key content>";
String clientKeyPass = "<your client key password>";

Client client = new Client(new Config()
    .setProtocol(protocol)
    .setEndpoint(endpoint)
    .setClientKeyContent(clientKey)
    .setPassword(clientKeyPass));

Bypassing SSL verification in development

In a development environment, use RuntimeOptions to skip trusted certificate verification. Do not use this in production.

import com.aliyun.dkms.gcs.openapi.util.models.RuntimeOptions;

RuntimeOptions runtimeOptions = new RuntimeOptions();
runtimeOptions.setIgnoreSSL(true);

client.encryptWithOptions(encryptRequest, runtimeOptions);

Encrypt data

Encrypts data using a symmetric CMK. Full example: AesEncryptDecryptSample.java.

import com.aliyun.dkms.gcs.sdk.Client;
import com.aliyun.dkms.gcs.sdk.models.*;

// The ID or alias of the symmetric CMK.
String cipherKeyId = "<your cipher key id>";
// The data to encrypt.
byte[] originData = "<your plaintext data>".getBytes();

EncryptRequest encryptRequest = new EncryptRequest();
encryptRequest.setKeyId(cipherKeyId);
encryptRequest.setPlaintext(originData);

EncryptResponse encryptResponse = client.encrypt(encryptRequest);
byte[] cipherData = encryptResponse.getCiphertextBlob(); // Encrypted ciphertext.
byte[] iv = encryptResponse.getIv();                     // Initialization vector (IV) — required for decryption.
String requestId = encryptResponse.getRequestId();       // Request ID for troubleshooting.

Decrypt data

Decrypts ciphertext using the same symmetric CMK. Pass the iv value returned by encrypt() — the initialization vector (IV) must match. Full example: AesEncryptDecryptSample.java.

import com.aliyun.dkms.gcs.sdk.Client;
import com.aliyun.dkms.gcs.sdk.models.*;

// The ID or alias of the symmetric CMK — must match the one used for encryption.
String cipherKeyId = "<your cipher key id>";
byte[] cipherData = encryptResponse.getCiphertextBlob(); // Ciphertext from encrypt().
byte[] iv = encryptResponse.getIv();                     // IV from encrypt() — must be identical.

DecryptRequest decryptRequest = new DecryptRequest();
decryptRequest.setKeyId(cipherKeyId);
decryptRequest.setCiphertextBlob(cipherData);
decryptRequest.setIv(iv);

DecryptResponse decryptResponse = client.decrypt(decryptRequest);
byte[] originData = decryptResponse.getPlaintext(); // Recovered plaintext.
String requestId = decryptResponse.getRequestId();

Generate a signature

Signs data using an asymmetric CMK. Full example: Sha256AsymmetricSignVerifySample.java.

import com.aliyun.dkms.gcs.sdk.Client;
import com.aliyun.dkms.gcs.sdk.models.*;

// The ID or alias of the asymmetric CMK.
String signerKeyId = "<the signer key id>";
byte[] message = "<the data to sign>".getBytes();

SignRequest signRequest = new SignRequest();
signRequest.setKeyId(signerKeyId);
signRequest.setMessage(message);

SignResponse signResponse = client.sign(signRequest);
byte[] signature = signResponse.getSignature(); // The generated signature.
String requestId = signResponse.getRequestId();

Verify a signature

Verifies a signature using the same asymmetric CMK. Full example: Sha256AsymmetricSignVerifySample.java.

import com.aliyun.dkms.gcs.sdk.Client;
import com.aliyun.dkms.gcs.sdk.models.*;

String signerKeyId = "<the signer key id>";
byte[] message = "<the data to verify>".getBytes();

VerifyRequest verifyRequest = new VerifyRequest();
verifyRequest.setKeyId(signerKeyId);
verifyRequest.setMessage(message);
verifyRequest.setSignature(signature); // The signature returned by sign().

VerifyResponse verifyResponse = client.verify(verifyRequest);
boolean valid = verifyResponse.getValue(); // true if the signature is valid.
String requestId = verifyResponse.getRequestId();

Retrieve a secret value

Retrieves a secret value stored in the dedicated KMS instance. Full example: GetSecretValueSample.java.

GetSecretValue requires SDK 0.2.6 or later.

import com.aliyun.dkms.gcs.sdk.Client;
import com.aliyun.dkms.gcs.sdk.models.*;

String secretName = "<your-secret-name>";

GetSecretValueRequest request = new GetSecretValueRequest()
    .setSecretName(secretName);

GetSecretValueResponse getSecretValueResponse = client.getSecretValue(request);
String secretData = getSecretValueResponse.getSecretData(); // The secret value.
String requestId = getSecretValueResponse.getRequestId();