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

背景信息

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

前提条件

  • 您已经启用专属KMS标准版实例并正常连接密码机,为实例创建密钥及应用接入点,并保存了Client Key及CA证书。具体操作,请参见快速入门
  • 已经获取专属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)