Key Management Service:KMS Instance SDK for PHP

Prerequisites

• A KMS instance is purchased and enabled. For more information, see Purchase and enable a KMS instance.

• A key and a secret are created. For more information, see Software-protected keys, Hardware-protected keys, and Create a secret.

  Note

  If your business does not require a secret, you do not need to create a secret.

• An application access point (AAP) is created, the client key that is bound to the AAP is saved, and a certificate authority (CA) certificate is obtained for the KMS instance. For more information, see Access a KMS instance by using an AAP.

• Make sure that the application runtime environment and the VPC of the KMS instance can communicate with each other.

  Business scenario	Description
  The application runtime environment and the KMS instance reside in the same region and belong to the same VPC.	By default, the application runtime environment and the KMS instance can communicate with each other. No manual configuration is required.
  The application runtime environment and the KMS instance reside in the same region but belong to different VPCs.	You must configure multiple VPCs to access the same KMS instance. For more information, see Access a KMS instance from multiple VPCs in the same region.

Install KMS Instance SDK for PHP

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

  1. Install AlibabaCloud DKMS-GCS SDK for PHP as a dependency by using the following methods.

     • Run the composer require alibabacloud/dkms-gcs-sdk in the root directory of your project.

     • 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

       We recommend that you install the latest version of the SDK. For more information, see Open source code repository.

  2. In the root directory of the project, run the composer install command to install the dependency.

  3. 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, see open source code repository.

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

Initialize KMS Instance SDK for PHP

To use KMS Instance SDK for PHP to initiate a request, you must create a client.

1. Create a client.

   <?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. KMS supports connections only over HTTPS. 
   $config->protocol = 'https';
   // The endpoint of your KMS instance. Set the value in the following format: <ID of your KMS instance >.cryptoservice.kms.aliyuncs.com. 
   $config->endpoint = '<yourKMSInstanceId>.cryptoservice.kms.aliyuncs.com';
   // The client key. 
   $config->clientKeyContent = '<your client key content>';
   // The password of the client key file. 
   $config->password = '<your client key password>';
   $client = new AlibabaCloudDkmsGcsSdkClient($config);
   $client = new AlibabaCloudDkmsGcsSdkClient($config);

2. Configure the certificate authority (CA) certificate of your KMS instance by using RuntimeOptions.

   Important

   To ensure communication security in the production environment, we recommend that you verify the validity of SSL/TLS certificates. If you do not need to verify the validity of SSL/TLS certificates in specific scenarios such as testing scenarios, set the ignoreSSL field of RuntimeOptions to true.

   Set the verify field of RuntimeOptions to the path of the CA certificate of the KMS instance. Sample code:

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

Use the client to call an operation

After you create a client, you can use the client to call KMS Instance API operations. The following sample codes provide examples on how to call operations in different scenarios. For more information about KMS Instance API, see List of operations by function.

• Call the Encrypt operation to encrypt data by using a symmetric key

  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 key. 
  $encryptRequest->keyId = '<your cipher key id>';
  // The data that you want to encrypt. 
  $encryptRequest->plaintext = AlibabaCloud\Tea\Utils\Utils::toBytes('encrypt plaintext');
  
  $encryptResponse = $client->encryptWithOptions($encryptRequest, $runtimeOptions);
  // The ciphertext. 
  $ciphertextBlob = $encryptResponse->ciphertextBlob;
  // The initial vector of Cipher, which is used to decrypt data. 
  $iv = $encryptResponse->iv;
  // The request ID. 
  $requestId = $encryptResponse->requestId;

• Call the Decrypt operation to decrypt data by using a symmetric key

  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 key. 
  $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 request ID. 
  $requestId = $decryptResponse->requestId;

• Call the Sign operation to sign data by using an asymmetric key

  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 key. 
  $signRequest->keyId = 'your cipher key id';
  // The data that you want to sign. 
  $signRequest->message = <the data to sign>;
  
  $signResponse = $client->signWithOptions($signRequest, $runtimeOptions);
  // The signature value. 
  $signature = $signResponse->signature;
  // The request ID. 
  $requestId = $signResponse->requestId;

• Call the Verify operation to verify a signature by using an asymmetric key

  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 key. 
  $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. 
  $verifyRequest->signature = <the signature to verify>;
  
  $verifyResponse = $client->verifyWithOptions($verifyRequest, $runtimeOptions);
  // The verification result. 
  $value = $verifyResponse->value;
  // The request ID. 
  $requestId = $verifyResponse->requestId;

• Call the GetSecretValue operation to retrieve a secret value

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

  Important

  This operation is supported only for KMS Instance SDK for PHP V0.2.2 or later.

  <?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 request ID. 
  $_requestId = $getSecretValueResponse->requestId;