KMS实例SDK for PHP

前提条件

• 已购买和启用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;