:Java専用KMS SDK

前提条件

• 専用KMSインスタンスを購入し、ハードウェアセキュリティモジュール (HSM) クラスターに接続します。 インスタンスの顧客マスターキー (CMK) とアプリケーションアクセスエンドポイント (AAP) が作成され、インスタンスのクライアントキーと認証機関 (CA) 証明書が保存されます。 詳細については、「Connect applications to the dedicated KMS instance of the Standard edition」をご参照ください。

  説明

  ダウンロードしたCA証明書の名前はPrivateKmsCA_kst-******.pem形式で、ダウンロードしたクライアント鍵ファイルの名前はClientKey_******.json形式です。

• 専用KMSインスタンスへのアクセスに使用される仮想プライベートクラウド (VPC) アドレスが取得されます。 VPCアドレスは次の要件を満たす必要があります。

  • VPCアドレスは、HSMクラスターの有効化時に指定されます。

  • VPCアドレスはコンピューターからアクセスできます。

  詳細については、「Standardエディションの専用KMSインスタンスの照会」をご参照ください。

専用KMS SDKのインストール

プロジェクトにalibabacloud-dkms-gcs-sdkの依存関係を追加します。 次に、Dedicated KMS SDKの公開されたJavaパッケージがMavenリポジトリから自動的にダウンロードされます。

<dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>alibabacloud-dkms-gcs-sdk</artifactId>
  <version>x.x.x</version>
</dependency>

専用KMS SDKの初期化

専用KMSインスタンスのJavaクライアントを作成して、専用KMSインスタンスによって管理されるリソースを呼び出すことができます。 たとえば、クライアントを使用して暗号化操作を実行し、秘密情報を取得できます。 専用KMS SDK for Javaを使用してAPIリクエストを開始する前に、クライアントを作成する必要があります。

Java 0.2.7以降の専用KMS SDK (推奨)

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

// The connection protocol between the dedicated KMS instance and the client. Set the value to https.
String protocol = "https";
// The VPC address of the dedicated KMS instance. The VPC address excludes the scheme https.
String endpoint = "<service_id>.cryptoservice.kms.aliyuncs.com";

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

// The password that is used to decrypt the client key of the dedicated KMS instance.
String clientKeyPass = "<your client key password>";

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) // The path to the CA certificate file or the content of the CA certificate. Configure this parameter based on your business requirements. 
                           //.setCa(caCert) // The content of the CA certificate. 
                           .setClientKeyFile(clientKeyFilePath)// The path to the client key file or the content of the client key file. Configure this parameter based on your business requirements. 
                           //.setClientKeyContent(clientKey)// The content of the client key file. 
                           .setPassword(clientKeyPass));

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

RuntimeOptions runtimeOptions = new RuntimeOptions();
runtimeOptions.setIgnoreSSL(true);
...
client.encryptWithOptions(encryptRequest, runtimeOptions);

Java 0.2.6およびそれ以前の専用KMS SDK

1. CA証明書を設定します。

   セキュアな接続が本番環境で確立されるようにするには、Java信頼証明書を設定します。

   1. CA証明書ファイルを2つのファイルに分割します。

      CA証明書は2つのファイルで構成され、各ファイルは ----- BEGIN certificate ------- で始まり、----- END CERTIFICATE ------- で終わります。 デフォルトでは、最初のファイルにはrootca.pemのコンテンツが含まれ、2番目のファイルには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コマンドを使用して、2つのファイルをJAVA_HOME/jre/lib/security/cacertsディレクトリにインポートします。

      • インポートファイル1: rootca.pem

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

      • インポートファイル2: subca.pem

        keytool -importcert -alias PrivateKmsCA_SubCA -keystore $JAVA_HOME/jre/lib/security/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インスタンスのクライアントを作成します。

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

例

• 専用KMSインスタンスのクライアントを使用して、対称CMKを使用してデータを暗号化するEncrypt操作を呼び出します。

  サンプルコードの詳細については、「ソースコード」をご参照ください。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  // The ID or alias of the symmetric CMK of the dedicated KMS instance. 
  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();

• 専用KMSインスタンスのクライアントを使用して、Decrypt操作を呼び出し、対称CMKを使用して暗号文を復号します。

  サンプルコードの詳細については、「ソースコード」をご参照ください。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  // The ID or alias of the symmetric CMK of the dedicated KMS instance. 
  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();

• 専用KMSインスタンスのクライアントを使用してSign操作を呼び出し、非対称CMKを使用して署名を生成します。

  サンプルコードの詳細については、「ソースコード」をご参照ください。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  // The ID or alias of the symmetric CMK of the dedicated KMS instance. 
  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();

• 専用KMSインスタンスのクライアントを使用してVerify操作を呼び出し、非対称CMKを使用して署名を検証します。

  サンプルコードの詳細については、「ソースコード」をご参照ください。

  import com.aliyun.dkms.gcs.sdk.Client;
  import com.aliyun.dkms.gcs.sdk.models.*;
  
  // The ID or alias of the symmetric CMK of the dedicated KMS instance. 
  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();

• 専用KMSインスタンスのクライアントを使用して、GetSecretValue操作を呼び出し、秘密値を照会します。

  サンプルコードの詳細については、「ソースコード」をご参照ください。

  説明

  Java 0.2.6以降の専用KMS SDKは、GetSecretValue操作をサポートしています。

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