前提條件

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

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

  說明

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

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

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

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