前提條件

• 已購買和啟用KMS實例。具體操作，請參見購買和啟用KMS實例。

• 已完成密鑰和憑據的創建。具體操作，請參見軟件密鑰、硬件密鑰、創建憑據。

  說明

  如果您的業務不涉及憑據，則無需創建憑據。

• 已創建應用接入點并保存了Client Key、獲取KMS實例CA證書。具體操作，請參見創建應用接入點。

• 請確保應用程序運行環境可訪問KMS實例VPC地址。

  業務場景	說明
  應用程序運行環境和KMS實例在同一個地域，且屬于同一個VPC	默認應用程序運行環境和KMS實例間網絡互通，您無需配置。
  應用程序運行環境和KMS實例在同一個地域，但屬于不同VPC	您需要配置多個VPC訪問同一個KMS實例，具體操作，請參見同地域多VPC訪問KMS實例。
  應用程序運行環境和KMS實例在不同地域	您需要配置應用跨地域訪問KMS實例。具體操作，請參見應用跨地域訪問KMS實例。

安裝SDK

• 方式一（推薦）：通過Composer來管理項目依賴

  1. 通過如下方式之一，安裝AlibabaCloud DKMS-GCS SDK for PHP作為依賴項。

     • 在項目的根目錄中運行composer require alibabacloud/dkms-gcs-sdk。

     • 在composer.json文件中添加依賴關系。

       "require": {
         "alibabacloud/dkms-gcs-sdk": "SDK版本"
         }

       說明

       建議您安裝SDK的最新版本，關于版本的更多信息，請參見開源代碼倉庫。

  2. 在項目的根目錄中，執行composer install安裝依賴。

  3. 使用Composer安裝完成后，在PHP代碼中引入依賴。

     require_once __DIR__ . '/vendor/autoload.php';

• 方式二：直接下載SDK源碼

  訪問開源代碼倉庫下載SDK源碼，在PHP代碼中引入SDK目錄下的autoload.php文件。

  require_once '/path/to/dkms-gcs-sdk/autoload.php';

初始化SDK客戶端

使用PHP SDK發起KMS實例API請求，您需要初始化一個Client實例。

1. 初始化Client實例。

   <?php
   
   use AlibabaCloud\Dkms\Gcs\Sdk\Client as AlibabaCloudDkmsGcsSdkClient;
   use AlibabaCloud\Dkms\Gcs\OpenApi\Models\Config as AlibabaCloudDkmsGcsOpenApiConfig;
   
   $config = new AlibabaCloudDkmsGcsOpenApiConfig();
   //連接協議請設置為"https"。KMS實例服務僅允許通過HTTPS協議訪問。
   $config->protocol = 'https';
   //設置endpoint為<your KMS Instance Id>.cryptoservice.kms.aliyuncs.com。
   $config->endpoint = '<yourKMSInstanceId>.cryptoservice.kms.aliyuncs.com';
   //Client Key。
   $config->clientKeyContent = '<your client key content>';
   //Client Key口令。
   $config->password = '<your client key password>';
   $client = new AlibabaCloudDkmsGcsSdkClient($config);

2. 通過配置運行時參數（RuntimeOptions）設置KMS實例的CA證書。

   重要

   為保障生產環境通信安全，建議您保持開啟驗證SSL/TLS證書有效性。如您確有需要關閉驗證SSL/TLS證書，例如線下測試場景，可通過將運行時參數（RuntimeOptions）的ignoreSSL字段設置為true實現。

   設置RuntimeOptions的verify字段為KMS實例CA證書路徑。代碼示例如下：

   <?php
   
   use AlibabaCloud\Dkms\Gcs\OpenApi\Util\Models\RuntimeOptions;
   
   $runtimeOptions = new RuntimeOptions();
   $runtimeOptions->verify = 'path/to/caCert.pem';

使用已初始化的Client調用KMS實例API

初始化Client后，您可以通過Client調用KMS實例API，本文介紹如下幾個使用場景和代碼示例。關于KMS實例API的詳細信息，請參見API概覽。

• 調用Encrypt接口使用對稱密鑰加密數據

  詳細代碼示例，請參見原始代碼。

  <?php
  
  require __DIR__ . '/vendor/autoload.php';
  
  use AlibabaCloud\Dkms\Gcs\Sdk\Models\EncryptRequest;
  
  $encryptRequest = new EncryptRequest();
  //密鑰的ID或別名（Alias）。
  $encryptRequest->keyId = '<your cipher key id>';
  //待加密數據。
  $encryptRequest->plaintext = AlibabaCloud\Tea\Utils\Utils::toBytes('encrypt plaintext');
  
  $encryptResponse = $client->encryptWithOptions($encryptRequest, $runtimeOptions);
  //密文。
  $ciphertextBlob = $encryptResponse->ciphertextBlob;
  //Cipher初始向量，用于解密數據。
  $iv = $encryptResponse->iv;
  //請求ID。
  $requestId = $encryptResponse->requestId;

• 調用Decrypt接口使用對稱密鑰解密密文

  詳細代碼示例，請參見原始代碼。

  <?php
  
  require __DIR__ . '/vendor/autoload.php';
  
  use AlibabaCloud\Dkms\Gcs\Sdk\Models\DecryptRequest;
  
  $decryptRequest = new DecryptRequest();
  //密鑰的ID或別名（Alias）。
  $decryptRequest->keyId = '<your cipher key id>';
  //待解密數據，加密返回的密文。
  $decryptRequest->ciphertextBlob = <your ciphertext>;
  //Cipher初始向量，必須與加密時一致。
  $decryptRequest->iv = <IV value>;
  
  $decryptResponse = $client->decryptWithOptions($decryptRequest, $runtimeOptions);
  //原始明文數據。
  $plaintext = $decryptResponse->plaintext;
  //請求ID。
  $requestId = $decryptResponse->requestId;

• 調用Sign接口使用非對稱密鑰進行數字簽名

  詳細代碼示例，請參見原始代碼。

  <?php
  
  require __DIR__ . '/vendor/autoload.php';
  
  use AlibabaCloud\Dkms\Gcs\Sdk\Models\SignRequest;
  
  $signRequest = new SignRequest();
  //密鑰的ID或別名（Alias）。
  $signRequest->keyId = 'your cipher key id';
  //待簽名數據。
  $signRequest->message = <the data to sign>;
  
  $signResponse = $client->signWithOptions($signRequest, $runtimeOptions);
  //簽名值。
  $signature = $signResponse->signature;
  //請求ID。
  $requestId = $signResponse->requestId;

• 調用Verify接口使用非對稱密鑰驗證數字簽名

  詳細代碼示例，請參見原始代碼。

  <?php
  
  require __DIR__ . '/vendor/autoload.php';
  
  use AlibabaCloud\Dkms\Gcs\Sdk\Models\VerifyRequest;
  
  $verifyRequest = new VerifyRequest();
  //密鑰的ID或別名（Alias）。
  $verifyRequest->keyId = 'your cipher key id';
  //待驗證簽名的數據。
  $verifyRequest->message = <the data to sign>;
  //待驗證簽名值。
  $verifyRequest->signature = <the signature to verify>;
  
  $verifyResponse = $client->verifyWithOptions($verifyRequest, $runtimeOptions);
  //驗簽結果。
  $value = $verifyResponse->value;
  //請求ID。
  $requestId = $verifyResponse->requestId;

• 調用GetSecretValue接口獲取憑據值

  詳細代碼示例，請參見原始代碼。

  重要

  0.2.2及以上版本的KMS實例SDK for PHP才支持獲取憑據值。

  <?php
  
  require __DIR__ . '/vendor/autoload.php';
  
  use AlibabaCloud\Dkms\Gcs\Sdk\Models\GetSecretValueRequest;
  
  // 您在KMS創建的憑據名稱。
  $secretName = '<your secret name>';
  
  $getSecretValueRequest = new GetSecretValueRequest([
      'secretName' => $secretName,
  ]);
  
  // 調用獲取憑據接口。
  $getSecretValueResponse = $client->getSecretValueWithOptions($getSecretValueRequest, $runtimeOptions);
  
  // 憑據值。
  $_secretData = $getSecretValueResponse->secretData;
  // 請求ID。
  $_requestId = $getSecretValueResponse->requestId;