专属KMS SDK for Go帮助您通过简单的编程访问专属KMS的API，实现加密解密、签名验签和获取凭据信息的业务诉求。

背景信息

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

前提条件

  • 您已经启用专属KMS实例并正常连接密码机，为实例创建密钥及应用接入点，并保存了Client Key及CA证书。具体操作，请参见快速入门。
    说明 CA证书下载后文件名默认为PrivateKmsCA_kst-******.pem，应用身份凭证文件下载后文件名默认为ClientKey_******.json。
  • 已经获取专属KMS实例VPC地址，并确保可以通过以下方式访问专属KMS实例VPC地址：
    • 在激活密码机实例集群时设置的VPC中访问专属KMS实例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

您可以初始化一个专属KMS标准版实例的Go客户端，用于调用专属KMS标准版实例管理的密钥等资源。使用Go SDK发起专属KMS API请求，您需要初始化一个Client实例，并根据需要修改Config的默认配置项。

  1. 配置CA证书。

    为保障生产环境通信安全，需要配置可信证书。

    将CA证书内容设定为RuntimeOptions的verify字段，示例代码如下：
    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)),
}
...
encryptResponse, err := client.EncryptWithOptions(encryptRequest, runtimeOptions)

    开发环境可使用RuntimeOptions的ignoreSSL字段临时忽略可信证书的验证。示例代码如下：

    import (
    dedicatedkmsopenapiutil "github.com/aliyun/alibabacloud-dkms-gcs-go-sdk/openapi-util"
    "github.com/alibabacloud-go/tea/tea"
)

// 忽略服务端证书
runtimeOptions := &dedicatedkmsopenapiutil.RuntimeOptions{
    IgnoreSSL: tea.Bool(true),
}
...
encryptResponse, err := client.EncryptWithOptions(encryptRequest, runtimeOptions)
  2. 创建专属KMS标准版Client。

    创建专属KMS标准版Client时，需要指定标准版实例的Endpoint。EndPoint为专属KMS标准版实例服务地址去掉https://。关于专属KMS标准版实例服务地址的更多信息，请参见查询专属KMS标准版实例。

    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
  Protocol: tea.String("https"),
  // 专属KMS标准版实例Client Key
    ClientKeyContent: tea.String("<your client key content>"),
  // 专属KMS标准版实例Client Key解密口令
    Password: tea.String("<your client key password>"),
  // Endpoint，专属KMS标准版实例的服务地址去掉'https://'
    Endpoint: tea.String("<service_id>.cryptoservice.kms.aliyuncs.com"),
}

client, err := dedicatedkmssdk.NewClient(config)

代码示例

  • 专属KMS标准版Client调用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")
// 专属KMS标准版实例加密密钥的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)
  • 专属KMS标准版Client调用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"
)

// 专属KMS标准版实例解密密钥的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)
  • 专属KMS标准版Client调用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"
)

// 专属KMS实例签名密钥的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)
  • 专属KMS标准版Client调用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"
)

// 专属KMS标准版实例签名密钥的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)
  • 使用专属KMS标准版Client调用GetSecretValue接口获取凭据值

    详细代码示例，请参见原始代码。

    重要 0.2.1及以上版本的专属KMS Go SDK才支持获取凭据值。
    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)