：KMS執行個體SDK for Go

前提條件

• 已購買和啟用KMS執行個體。具體操作，請參見購買和啟用KMS執行個體。

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

  說明

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

• 已建立應用存取點並儲存了Client Key、擷取KMS執行個體CA認證。具體操作，請參見建立應用存取點。

• 請確保應用程式運行環境可訪問KMS執行個體VPC地址。

  業務情境	說明
  應用程式運行環境和KMS執行個體在同一個地區，且屬於同一個VPC	預設應用程式運行環境和KMS執行個體間網路互連，您無需配置。
  應用程式運行環境和KMS執行個體在同一個地區，但屬於不同VPC	您需要配置多個VPC訪問同一個KMS執行個體，具體操作，請參見同地區多VPC訪問KMS執行個體。

安裝SDK

• 方式一：使用go.mod管理您的依賴。

  在go.mod檔案中添加以下內容安裝依賴包。

  require (
      github.com/aliyun/alibabacloud-dkms-gcs-go-sdk SDK版本
  )

  說明

  建議您安裝SDK的最新版本，關於版本的更多資訊，請參見開原始碼倉庫。

• 方式二：使用go get擷取遠程程式碼封裝。

  $ go get -u github.com/aliyun/alibabacloud-dkms-gcs-go-sdk

初始化SDK

使用Go SDK發起KMS執行個體API請求，您需要初始化一個Client執行個體。

1. 初始化Client執行個體。

   import (
       dedicatedkmsopenapi "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/openapi"
       dedicatedkmssdk "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/sdk"
     "github.com/alibabacloud-go/tea/tea"
   )
   
   config := &dedicatedkmsopenapi.Config{
     // 連線協定請設定為"https"。KMS執行個體服務僅允許通過HTTPS協議訪問。
     Protocol: tea.String("https"),  
     // 設定endpoint為<your KMS Instance Id>.cryptoservice.kms.aliyuncs.com。
       Endpoint: tea.String("<your KMS Instance Id>.cryptoservice.kms.aliyuncs.com"),
     // Client Key。
       ClientKeyContent: tea.String("<your client key content>"),
     // Client Key口令。
       Password: tea.String("<your client key password>"),
   }
   
   client, err := dedicatedkmssdk.NewClient(config)

2. 通過配置運行時參數（RuntimeOptions）設定KMS執行個體的CA認證。

   重要

   為保障生產環境通訊安全，建議您保持開啟驗證SSL/TLS認證有效性。如您確有需要關閉驗證SSL/TLS認證，例如線下測試情境，可通過將運行時參數（RuntimeOptions）的IgnoreSSL欄位設定為true實現。

   設定RuntimeOptions的verify欄位為KMS執行個體CA憑證路徑。程式碼範例如下：

   import (
       dedicatedkmsopenapiutil "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/openapi-util"
       "github.com/alibabacloud-go/tea/tea"
       "io/ioutil"
   )
   
   // 驗證服務端認證
   ca, err := ioutil.ReadFile("path/to/caCert.pem")
   if err != nil {
       panic(err)
   }
   runtimeOptions := &dedicatedkmsopenapiutil.RuntimeOptions{
       Verify: tea.String(string(ca)),
   }

使用已初始化的Client調用KMS執行個體API

初始化Client後，您可以通過Client調用KMS執行個體API，本文介紹如下幾個使用情境和程式碼範例。關於KMS執行個體API的詳細資料，請參見API概覽。

• 調用Encrypt介面使用對稱金鑰密碼編譯資料

  詳細程式碼範例，請參見原始代碼。

  import (
      dedicatedkmsopenapi "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/openapi"
      dedicatedkmssdk "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/sdk"
      "github.com/alibabacloud-go/tea/tea"
  )
  
  // 待加密資料。
  plaintext := []byte("encrypt plaintext")
  // 密鑰的ID或別名（Alias）。
  keyId := "<your cipher key id>"
  
  encryptRequest := &dedicatedkmssdk.EncryptRequest{
      KeyId:     tea.String(keyId),
      Plaintext: plaintext,
  }
  
  encryptResponse, err := client.EncryptWithOptions(encryptRequest, runtimeOptions)
  if err != nil {
      panic(err)
  }
  
  // 密文。
  cipher := encryptResponse.CiphertextBlob
  // Cipher初始向量，用於解密資料。
  iv := encryptResponse.Iv
  // 請求ID。
  requestId := tea.StringValue(encryptResponse.RequestId)

• 調用Decrypt介面使用對稱金鑰解密密文

  詳細程式碼範例，請參見原始代碼。

  import (
      dedicatedkmsopenapi "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/openapi"
      dedicatedkmssdk "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/sdk"
      "github.com/alibabacloud-go/tea/tea"
  )
  
  // 密鑰的ID或別名（Alias）。
  keyId := "<your cipher key id>"
  // 待解密資料，加密返回的密文。
  ciphertextBlob := []byte("<your cipher data to decrypt>")
  // Cipher初始向量，必須與加密時一致。
  iv := []byte("<IV value>")
  
  decryptRequest := &dedicatedkmssdk.DecryptRequest{
      KeyId:          tea.String(keyId),
      CiphertextBlob: ciphertextBlob,
      Iv:             iv,
  }
  
  decryptResponse, err := client.DecryptWithOptions(decryptRequest, runtimeOptions)
  if err != nil {
      panic(err)
  }
  
  // 原始明文資料。
  plaintext := decryptResponse.Plaintext
  // 請求ID。
  requestId := tea.StringValue(decryptResponse.RequestId)

• 調用Sign介面使用非對稱金鑰進行數位簽章

  詳細程式碼範例，請參見原始代碼。

  import (
      dedicatedkmsopenapi "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/openapi"
      dedicatedkmssdk "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/sdk"
      "github.com/alibabacloud-go/tea/tea"
  )
  
  // 密鑰的ID或別名（Alias）。
  signerKeyId := "<the signer key id>"
  // 待簽名資料。
  message := []byte("<the data to sign>")
  
  signRequest := &dedicatedkmssdk.SignRequest{
      KeyId:       tea.String(signerKeyId),
      Message:     message,
      MessageType: tea.String(messageType),
  }
  
  signResponse, err := client.SignWithOptions(signRequest, runtimeOptions)
  if err != nil {
      panic(err)
  }
  
  // 簽名值。
  signature := signResponse.Signature
  // 請求ID。
  requestId := tea.StringValue(signResponse.RequestId)

• 調用Verify介面使用非對稱金鑰驗證數位簽章

  詳細程式碼範例，請參見原始代碼。

  import (
      dedicatedkmsopenapi "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/openapi"
      dedicatedkmssdk "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/sdk"
      "github.com/alibabacloud-go/tea/tea"
  )
  
  // 密鑰的ID或別名（Alias）。
  signerKeyId := "<the signer key id>"
  // 待驗證簽名的資料。
  message := []byte("<the data to sign>")
  
  // 待驗證簽名值。
  signature := []byte("<the signature>")
  
  verifyRequest := &dedicatedkmssdk.VerifyRequest{
      KeyId:       tea.String(signerKeyId),
      Message:     message,
      MessageType: tea.String(messageType),
      Signature:   signature,
  }
  
  verifyResponse, err := client.VerifyWithOptions(verifyRequest, runtimeOptions)
  if err != nil {
      panic(err)
  }
  
  // 驗簽結果。
  value := tea.BoolValue(verifyResponse.Value)
  // 請求ID。
  requestId := tea.StringValue(verifyResponse.RequestId)

• 調用GetSecretValue介面擷取憑據值

  詳細程式碼範例，請參見原始代碼。

  重要

  0.2.1及以上版本的KMS執行個體SDK for Go才支援擷取憑據值。

  import (
      dedicatedkmsopenapi "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/openapi"
      dedicatedkmssdk "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/sdk"
      "github.com/alibabacloud-go/tea/tea"
  )
  
  // 憑據名稱。
  secretName := "<your-dkms-secret-name>"
  
  getSecretValueRequest := &dedicatedkmssdk.GetSecretValueRequest{
      SecretName: tea.String(secretName),
  }
  
  // 調用擷取憑據值介面。
  response, err := client.GetSecretValueWithOptions(getSecretValueRequest, runtimeOptions)
  if err != nil {
      panic(err)
  }
  
  // 憑據值。
  _secretData := tea.StringValue(response.SecretData)
  // 請求ID。
  _RequestId := tea.StringValue(response.RequestId)