KMS实例SDK for Go - 密钥管理服务

KMS实例SDK for Go帮助您通过简单的编程访问KMS实例API，实现加密解密、签名验签和获取凭据值的业务诉求。本文介绍如何安装SDK以及如何调用接口进行加密解密、签名验签和获取凭据值。

背景信息

KMS提供了多种类型的开发工具（SDK），请您在使用前先了解各SDK的使用场景。更多信息，请参见SDK使用指引。

您可以访问开源代码仓库，查看SDK源码及代码示例。同时也欢迎您提出宝贵意见，或者提供代码示例。

前提条件

已购买和启用KMS实例。具体操作，请参见购买和启用KMS实例。
已完成密钥和凭据的创建。具体操作，请参见软件密钥、硬件密钥、创建凭据。
说明
如果您的业务不涉及凭据，则无需创建凭据。
已创建应用接入点并保存了Client Key、获取KMS实例CA证书。具体操作，请参见通过应用接入点访问KMS实例。

请确保应用程序运行环境可访问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实例。

初始化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)

通过配置运行时参数（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)