Dedicated KMS SDK for Java allows you to call the API operations of Dedicated Key Management Service (KMS) in a convenient manner. Dedicated KMS SDK for Java is suitable for business scenarios such as data encryption, data decryption, signature generation, signature verification, and secret value queries.

Background information

You can visit the open source code repository to view the source code and sample code of Dedicated KMS SDK. You are welcome to share your comments or provide your sample code.

Prerequisites

  • A dedicated KMS instance of the Standard edition is purchased and connected to a hardware security module (HSM) cluster. A customer master key (CMK) and an application access endpoint (AAP) are created for the instance, and the client key and certification authority (CA) certificate of the instance are saved. For more information, see Getting started with Dedicated KMS of the Standard edition.
  • The virtual private cloud (VPC) address that is used to access the dedicated KMS instance of the Standard edition is obtained. The VPC address must meet the following requirements:
    • The VPC address is specified when the HSM cluster is activated.
    • The VPC address can be accessed from your computer.

    For more information, see Query a dedicated KMS instance of the Standard edition.

Install Dedicated KMS SDK

Add the alibabacloud-dkms-gcs-sdk dependency to your project. Then, a published Java package of Dedicated KMS SDK is automatically downloaded from the Maven repository.

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>alibabacloud-dkms-gcs-sdk</artifactId>
  <version>x.x.x</version>
</dependency>
Note To obtain the latest version of Dedicated KMS SDK, visit Dedicated KMS SDK for Java.

Initialize Dedicated KMS SDK

You can create a Java client for a dedicated KMS instance of the Standard edition to call the resources that are managed by the dedicated KMS instance. For example, you can use the client to call the keys that are managed by the instance. Before you can use Dedicated KMS SDK for Java to initiate an API request, you must create a client and modify the default settings of Config based on your business requirements.

  1. Configure a CA certificate.

    To ensure that secure connections are established in the production environment, configure a Java-trusted certificate. The following steps describe how to configure a Java-trusted certificate:

    1. Split the CA certificate into two files.

      A CA certificate contains two parts, and each part starts ------BEGIN CERTIFICATE -------- and ends with ------END CERTIFICATE --------. By default, the first part contains the content of rootca.pem and the second part contains the content of subca.pem.

      • File 1: rootca.pem
        -----BEGIN CERTIFICATE-----
        <Root CA Certificate BASE64 Content>
        -----END CERTIFICATE-----
      • File 2: subca.pem
        -----BEGIN CERTIFICATE-----
        <Sub CA Certificate BASE64 Content>
        -----END CERTIFICATE-----
    2. Import the two files to the JAVA_HOME/jre/lib/security/cacerts directory by using keytool commands.
      • Import File 1: rootca.pem
        keytool -importcert -alias PrivateKmsCA_RootCA -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file rootca.pem
      • Import File 2: subca.pem
        keytool -importcert -alias PrivateKmsCA_SubCA -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -file subca.pem
    3. Verify code.
      URL serviceUrl = new URL("https://<service_id>.cryptoservice.kms.aliyuncs.com");
      serviceUrl.openConnection().connect();
      Note If javax.net.ssl.SSLHandshakeException is not reported, the configuration is correct.

    In the development environment, you can use RuntimeOptions to temporarily ignore the verification of a trusted certificate. Sample code:

    import com.aliyun.dkms.gcs.openapi.util.models.RuntimeOptions;
    
    RuntimeOptions runtimeOptions = new RuntimeOptions();
    runtimeOptions.setIgnoreSSL(true);
    ...
    client.encryptWithOptions(encryptRequest, runtimeOptions);
  2. Create a client for the dedicated KMS instance of the Standard edition.

    When you create a client for a dedicated KMS instance of the Standard edition, you must specify the endpoint of the instance. The endpoint excludes the scheme https. For more information about the endpoint of a dedicated KMS instance of the Standard edition, see Query a dedicated KMS instance of the Standard edition.

    import com.aliyun.dkms.gcs.openapi.models.Config;
    import com.aliyun.dkms.gcs.sdk.Client;
    
    // The connection protocol. Set the value to https. 
    String protocol = "https";
    // The endpoint of the dedicated KMS instance of the Standard edition. The endpoint excludes the scheme https. 
    String endpoint = "<service_id>.cryptoservice.kms.aliyuncs.com";
    // The client key of the dedicated KMS instance of the Standard edition. 
    String clientKey = "<your client key>";
    // The password that is used to decrypt the client key of the dedicated KMS instance of the Standard edition. 
    String clientKeyPass = "<your client key password>";
    
    Client client = new Client(new Config()
                               .setProtocol(protocol)
                               .setEndpoint(endpoint)
                               .setClientKeyContent(clientKey)
                               .setPassword(clientKeyPass));

Examples

  • Use the client of a dedicated KMS instance of the Standard edition to call the Encrypt operation to encrypt data by using a symmetric CMK.

    For more information about the sample code, see Source code.

    import com.aliyun.dkms.gcs.sdk.Client;
    import com.aliyun.dkms.gcs.sdk.models.*;
    
    // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
    String cipherKeyId = "<your cipher key id>";
    // The data that you want to encrypt. 
    byte[] originData = <your origin data to encrypt>;
    
    EncryptRequest encryptRequest = new EncryptRequest();
    encryptRequest.setKeyId(cipherKeyId);
    encryptRequest.setPlaintext(originData);
    
    EncryptResponse encryptResponse = client.encrypt(encryptRequest);
    // The ciphertext. 
    byte[] cipherData = encryptResponse.getCiphertextBlob();
    // The initial vector of Cipher that is used to decrypt data. 
    byte[] iv = encryptResponse.getIv();
    // The ID of the request. 
    String requestId = encryptResponse.getRequestId();
  • Use the client of a dedicated KMS instance of the Standard edition to call the Decrypt operation to decrypt the ciphertext by using a symmetric CMK.

    For more information about the sample code, see Source code.

    import com.aliyun.dkms.gcs.sdk.Client;
    import com.aliyun.dkms.gcs.sdk.models.*;
    
    // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
    String cipherKeyId = "<your cipher key id>";
    // The ciphertext that you want to decrypt. 
    byte[] cipherData = <your cipher data to decrypt>;
    // The initial vector of Cipher. The initial vector must be the same as the initial vector that is specified for encryption. 
    byte[] iv = <IV value>;
    
    DecryptRequest decryptRequest = new DecryptRequest();
            decryptRequest.setKeyId(cipherKeyId);
            decryptRequest.setCiphertextBlob(cipherData);
            decryptRequest.setIv(iv);
    
    DecryptResponse decryptResponse = client.decrypt(decryptRequest);
    // The plaintext. 
    byte[] originData = decryptResponse.getPlaintext();
    // The ID of the request. 
    String requestId = decryptResponse.getRequestId();
  • Use the client of a dedicated KMS instance of the Standard edition to call the Sign operation to generate a signature by using an asymmetric CMK.

    For more information about the sample code, see Source code.

    import com.aliyun.dkms.gcs.sdk.Client;
    import com.aliyun.dkms.gcs.sdk.models.*;
    
    // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
    String signerKeyId = "<the signer key id>";
    // The data to sign. 
    byte[] message = <the data to sign>;
    
    SignRequest signRequest = new SignRequest();
    signRequest.setKeyId(signKeyId);
    signRequest.setMessage(message);
    
    SignResponse signResponse = client.sign(signRequest);
    // The signature value. 
    byte[] signature = signResponse.getSignature();
    // The ID of the request. 
    String requestId = signResponse.getRequestId();
  • Use the client of a dedicated KMS instance of the Standard edition to call the Verify operation to verify a signature by using an asymmetric CMK.

    For more information about the sample code, see Source code.

    import com.aliyun.dkms.gcs.sdk.Client;
    import com.aliyun.dkms.gcs.sdk.models.*;
    
    // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
    String signerKeyId = "<the signer key id>";
    // The data for which you want to verify the signature. 
    byte[] message = <the data to sign>;
    
    VerifyRequest verifyRequest = new VerifyRequest();
    verifyRequest.setKeyId(signerKeyId);
    verifyRequest.setMessage(message);
    verifyRequest.setSignature(signature);
    
    VerifyResponse verifyResponse = client.verify(verifyRequest);
    // The verification result. 
    boolean valid = verifyResponse.getValue();
    // The ID of the request. 
    String requestId = verifyResponse.getRequestId();
  • Use the client of a dedicated KMS instance of the Standard edition to call the GetSecretValue operation to query a secret value.

    For more information about the sample code, see Source code.

    Note Dedicated KMS SDK for Java V0.2.6 and later support the GetSecretValue operation.
    import com.aliyun.dkms.gcs.sdk.Client;
    import com.aliyun.dkms.gcs.sdk.models.*;
    
    // The secret name.
    String secretName = "<your-secret-name>";
    
    GetSecretValueRequest request = new GetSecretValueRequest()
                    .setSecretName(secretName);
    
    GetSecretValueResponse getSecretValueResponse = client.getSecretValue(request);
    // The secret value.
    String secretData = getSecretValueResponse.getSecretData();
    // The ID of the request.
    String requestId = getSecretValueResponse.getRequestId();