Key Management Service:Dedicated KMS SDK for PHP

Prerequisites

• A dedicated KMS instance 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 Connect applications to the dedicated KMS instance of the Standard edition.
  Note The downloaded CA certificate is named in the PrivateKmsCA_kst-******.pem format and the downloaded client key file is named in the ClientKey_******.json format.
• The virtual private cloud (VPC) address that is used to access the dedicated KMS instance 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

• Method 1 (Recommended): Use Composer to manage the project dependency

  1. Switch to the project directory on the client and execute the following code to install AlibabaCloud DKMS-GCS SDK for PHP as a dependency.

     composer require alibabacloud/dkms-gcs-sdk

  2. Add the following content to the composer.json file to declare the dependency on AlibabaCloud DKMS-GCS SDK for PHP:

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

     Note For more information about the latest version of Dedicated KMS SDK, visit the open source code repository.
  3. Switch to the project directory on the client and run the following code to install the dependency:

     composer install

  4. After the dependency is installed, reference the dependency in the PHP code.

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

• Method 2: Download the SDK source code

  Download the SDK source code from the open source code repository and reference the autoload.php file in the SDK directory to the PHP code. For more information about the SDK source code, visit open source code repository.

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

Initialize Dedicated KMS SDK

You can create a PHP client for a dedicated KMS instance of the Standard edition to call 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 PHP 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 certification authority (CA) certificate.

   To ensure secure communications in the production environment, you must configure a PHP-trusted certificate.

   Configure the verify field in RuntimeOptions. Sample code:

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

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

   <?php
   
   use AlibabaCloud\Dkms\Gcs\OpenApi\Util\Models\RuntimeOptions;
   
   $runtimeOptions = new RuntimeOptions();
   $runtimeOptions->ignoreSSL = true;
   
   ...
   $encryptResponse = $client->encryptWithOptions($encryptRequest, $runtimeOptions);

2. Create a client for the dedicated KMS instance of the Standard edition.

   When you create a client for the 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.

   <?php
   
   use AlibabaCloud\Dkms\Gcs\Sdk\Client as AlibabaCloudDkmsGcsSdkClient;
   use AlibabaCloud\Dkms\Gcs\OpenApi\Models\Config as AlibabaCloudDkmsGcsOpenApiConfig;
   
   $config = new AlibabaCloudDkmsGcsOpenApiConfig();
   // The connection protocol. Set the value to https. 
   $config->protocol = 'https';
   // The client key of the dedicated KMS instance of the Standard edition. 
   $config->clientKeyContent = '<your client key content>';
   // The password that is used to decrypt the client key of the dedicated KMS instance of the Standard edition. 
   $config->password = '<your client key password>';
   // The endpoint of the dedicated KMS instance of the Standard edition. The endpoint excludes the scheme https. 
   // Example:<service_id>.cryptoservice.kms.aliyuncs.com;
   $config->endpoint = '<your dkms instance service address>';
   
   $client = new AlibabaCloudDkmsGcsSdkClient($config);

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.

  <?php
  
  require __DIR__ . '/vendor/autoload.php';
  
  use AlibabaCloud\Dkms\Gcs\Sdk\Models\EncryptRequest;
  
  $encryptRequest = new EncryptRequest();
  // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
  $encryptRequest->keyId = '<your cipher key id>';
  // The data that you want to encrypt. 
  $encryptRequest->plaintext = \AlibabaCloud\Dkms\Gcs\OpenApi\Util\Utils::toBytes('encrypt plaintext');
  
  $encryptResponse = $client->encryptWithOptions($encryptRequest, $runtimeOptions);
  // The ciphertext. 
  $ciphertextBlob = $encryptResponse->ciphertextBlob;
  // The initial vector of Cipher that is used to decrypt data. 
  $iv = $encryptResponse->iv;
  // The ID of the request. 
  $requestId = $encryptResponse->requestId;

• 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.

  <?php
  
  require __DIR__ . '/vendor/autoload.php';
  
  use AlibabaCloud\Dkms\Gcs\Sdk\Models\DecryptRequest;
  
  $decryptRequest = new DecryptRequest();
  // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
  $decryptRequest->keyId = '<your cipher key id>';
  // The ciphertext that you want to decrypt. 
  $decryptRequest->ciphertextBlob = <your ciphertext>;
  // The initial vector of Cipher. The initial vector must be the same as the initial vector that is specified for encryption. 
  $decryptRequest->iv = <IV value>;
  
  $decryptResponse = $client->decryptWithOptions($decryptRequest, $runtimeOptions);
  // The plaintext. 
  $plaintext = $decryptResponse->plaintext;
  // The ID of the request. 
  $requestId = $decryptResponse->requestId;

• 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.

  <?php
  
  require __DIR__ . '/vendor/autoload.php';
  
  use AlibabaCloud\Dkms\Gcs\Sdk\Models\SignRequest;
  
  $signRequest = new SignRequest();
  // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
  $signRequest->keyId = 'your cipher key id';
  // The data to sign. 
  $signRequest->message = <the data to sign>;
  
  $signResponse = $client->signWithOptions($signRequest, $runtimeOptions);
  // The signature value. 
  $signature = $signResponse->signature;
  // The ID of the request. 
  $requestId = $signResponse->requestId;

• 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.

  <?php
  
  require __DIR__ . '/vendor/autoload.php';
  
  use AlibabaCloud\Dkms\Gcs\Sdk\Models\VerifyRequest;
  
  $verifyRequest = new VerifyRequest();
  // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
  $verifyRequest->keyId = 'your cipher key id';
  // The data for which you want to verify the signature. 
  $verifyRequest->message = <the data to sign>;
  // The signature value that you want to verify. 
  $verifyRequest->signature = <the signature to verify>;
  
  $verifyResponse = $client->verifyWithOptions($verifyRequest, $runtimeOptions);
  // The verification result. 
  $value = $verifyResponse->value;
  // The ID of the request. 
  $requestId = $verifyResponse->requestId;

• 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.

  Important Dedicated KMS SDK for PHP V0.2.2 and later support the GetSecretValue operation.

  <?php
  
  require __DIR__ . '/vendor/autoload.php';
  
  use AlibabaCloud\Dkms\Gcs\Sdk\Models\GetSecretValueRequest;
  
  // The secret name. 
  $secretName = '<your secret name>';
  
  $getSecretValueRequest = new GetSecretValueRequest([
      'secretName' => $secretName,
  ]);
  
  // The call process. 
  $getSecretValueResponse = $client->getSecretValueWithOptions($getSecretValueRequest, $runtimeOptions);
  
  // The secret value. 
  $_secretData = $getSecretValueResponse->secretData;
  // The ID of the request. 
  $_requestId = $getSecretValueResponse->requestId;