Key Management Service:Dedicated KMS SDK for Go

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: Use the go.mod file to manage dependencies.

  Add the following content to the go.mod file to install the dependency package.

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

  Note For more information about the latest version of Dedicated KMS SDK, visit the open source code repository.
• Method 2: Run the go get command to obtain a remote code package.

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

Initialize Dedicated KMS SDK

You can create a Go 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 Go 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 trusted certificate.

   Set the verify field in RuntimeOptions to the content of the CA certificate. Sample code:

   import (
       dedicatedkmsopenapiutil "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/openapi-util"
       "github.com/alibabacloud-go/tea/tea"
       "io/ioutil"
   )
   
   // Verify the certificate.
   ca, err := ioutil.ReadFile("path/to/caCert.pem")
   if err != nil {
       panic(err)
   }
   runtimeOptions := &dedicatedkmsopenapiutil.RuntimeOptions{
       Verify: tea.String(string(ca)),
   }
   ...
   encryptResponse, err := 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:

   import (
       dedicatedkmsopenapiutil "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/openapi-util"
       "github.com/alibabacloud-go/tea/tea"
   )
   
   // Ignore the certificate.
   runtimeOptions := &dedicatedkmsopenapiutil.RuntimeOptions{
       IgnoreSSL: tea.Bool(true),
   }
   ...
   encryptResponse, err := 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.

   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{
     // The connection protocol. Set the value to https.
     Protocol: tea.String("https"),
     // The client key of the dedicated KMS instance of the Standard edition.
       ClientKeyContent: tea.String("<your client key content>"),
     // The password that is used to decrypt the client key of the dedicated KMS instance of the Standard edition.
       Password: tea.String("<your client key password>"),
     // The endpoint of the dedicated KMS instance of the Standard edition. The endpoint excludes the scheme https.
       Endpoint: tea.String("<service_id>.cryptoservice.kms.aliyuncs.com"),
   }
   
   client, err := dedicatedkmssdk.NewClient(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.

  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"
  )
  
  // The data that you want to encrypt. 
  plaintext := []byte("encrypt plaintext")
  // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
  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)
  }
  
  // The ciphertext. 
  cipher := encryptResponse.CiphertextBlob
  // The initial vector of Cipher that is used to decrypt data. 
  iv := encryptResponse.Iv
  // The ID of the request. 
  requestId := tea.StringValue(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.

  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"
  )
  
  // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
  keyId := "<your cipher key id>"
  // The ciphertext that you want to decrypt. 
  ciphertextBlob := []byte("<your cipher data to decrypt>")
  // The initial vector of Cipher. The initial vector must be the same as the initial vector that is specified for encryption. 
  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)
  }
  
  // The plaintext. 
  plaintext := decryptResponse.Plaintext
  // The ID of the request. 
  requestId := tea.StringValue(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.

  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"
  )
  
  // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
  signerKeyId := "<the signer key id>"
  // The data to sign. 
  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)
  }
  
  // The signature value. 
  signature := signResponse.Signature
  // The ID of the request. 
  requestId := tea.StringValue(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.

  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"
  )
  
  // The ID or alias of the CMK of the dedicated KMS instance of the Standard edition. 
  signerKeyId := "<the signer key id>"
  // The data for which you want to verify the signature. 
  message := []byte("<the data to sign>")
  
  // The signature value that you want to verify. 
  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)
  }
  
  // The verification result. 
  value := tea.BoolValue(verifyResponse.Value)
  // The ID of the request. 
  requestId := tea.StringValue(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 Go V0.2.1 and later support the GetSecretValue operation.

  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"
  )
  
  // The secret name. 
  secretName := "<your-dkms-secret-name>"
  
  getSecretValueRequest := &dedicatedkmssdk.GetSecretValueRequest{
      SecretName: tea.String(secretName),
  }
  
  // The call process. 
  response, err := client.GetSecretValueWithOptions(getSecretValueRequest, runtimeOptions)
  if err != nil {
      panic(err)
  }
  
  // The secret value. 
  _secretData := tea.StringValue(response.SecretData)
  // The ID of the request. 
  _RequestId := tea.StringValue(response.RequestId)