全部产品
Search
文档中心

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

更新时间:Oct 09, 2023

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实例。

  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实现。

    设置RuntimeOptionsverify字段为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)