Managed data keys

Permission to retrieve data key plaintext and query versions

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:ListManagedDataKeyVersions",
        "kms:GetSecretValue",
        "kms:GetManagedDataKey"
      ],
      "Resource": [
        "acs:kms:{regionId}:{aliuid}:secret/kms-datakey!{dataKeyName}",
        "acs:kms:{regionId}:{aliuid}:secret/kms-datakeyversion!{dataKeyName}!*"
      ]
    }
  ]
}

Permission to decrypt data key material

When retrieving the data key plaintext, KMS must use the CMK to decrypt the key material. Therefore, the application also needs the Decrypt permission on the corresponding CMK.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt"
      ],
      "Resource": [
        "acs:kms:{regionId}:{aliuid}:key/{keyId}"
      ]
    }
  ]
}

Parameters

• {regionId}: The region ID of the KMS instance, such as cn-hangzhou.

• {aliuid}: The Alibaba Cloud account ID.

• {dataKeyName}: The data key name. The first line in Resource grants permission for the primary secret, and the second line grants permission for all version secrets by using the wildcard *.

• {keyId}: The ID of the CMK.

Encrypt data

During encryption, the latest version of the data key is used. The version identifier is prepended to the ciphertext header for key version identification during decryption.

package main

import (
    "crypto/aes"
    "crypto/cipher"
    cryptorand "crypto/rand"
    "encoding/base64"
    "io"
    "os"

    openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
    kmsclient "github.com/alibabacloud-go/kms-20160120/v4/client"
    "github.com/alibabacloud-go/tea/tea"
)

func EncryptWithManagedDataKey(plaintext []byte, dataKeyName string) ([]byte, error) {
    kms, err := kmsclient.NewClient(&openapi.Config{
        AccessKeyId:     tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")),
        AccessKeySecret: tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")),
        Endpoint:        tea.String("kms.cn-hangzhou.aliyuncs.com"),
    })
    if err != nil {
        return nil, err
    }

    // Retrieve the latest version of the managed data key plaintext. You can also manually download the key plaintext.
    getResp, err := kms.GetManagedDataKey(&kmsclient.GetManagedDataKeyRequest{
        DataKeyName: tea.String(dataKeyName),
        UseLatest:   tea.Bool(true),
    })
    if err != nil {
        return nil, err
    }
    dataKeyVersionId := tea.StringValue(getResp.Body.DataKeyVersionId)
    b64PlainDataKey := tea.StringValue(getResp.Body.Plaintext)
    // Decode the Base64-encoded string.
    plainDataKey, err := base64.StdEncoding.DecodeString(b64PlainDataKey)
    if err != nil {
        return nil, err
    }

    // Encrypt the data by using AES-GCM.
    block, err := aes.NewCipher(plainDataKey)
    if err != nil {
        return nil, err
    }
    gcm, err := cipher.NewGCM(block)
    if err != nil {
        return nil, err
    }
    nonce := make([]byte, gcm.NonceSize())
    _, err = io.ReadFull(cryptorand.Reader, nonce)
    if err != nil {
        return nil, err
    }

    ciphertext := gcm.Seal(nonce, nonce, plaintext, nil)
    // Prepend the version identifier (fixed 8 bytes) to the ciphertext for key version identification during decryption.
    output := append([]byte(dataKeyVersionId), ciphertext...)
    return output, nil
}

Decrypt data

During decryption, the version identifier is parsed from the ciphertext header to retrieve the corresponding data key version for decryption.

package main

import (
    "crypto/aes"
    "crypto/cipher"
    "encoding/base64"
    "fmt"
    "os"

    openapi "github.com/alibabacloud-go/darabonba-openapi/v2/client"
    kmsclient "github.com/alibabacloud-go/kms-20160120/v4/client"
    "github.com/alibabacloud-go/tea/tea"
)

func DecryptWithManagedDataKey(encrypted []byte, dataKeyName string) ([]byte, error) {
    kms, err := kmsclient.NewClient(&openapi.Config{
        AccessKeyId:     tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")),
        AccessKeySecret: tea.String(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")),
        Endpoint:        tea.String("kms.cn-hangzhou.aliyuncs.com"),
    })
    if err != nil {
        return nil, err
    }

    // Parse the version identifier (first 8 bytes) from the ciphertext header.
    dataKeyVersionId := string(encrypted[:8])
    ciphertext := encrypted[8:]

    // Retrieve the managed data key plaintext for the specified version.
    getResp, err := kms.GetManagedDataKey(&kmsclient.GetManagedDataKeyRequest{
        DataKeyName:      tea.String(dataKeyName),
        DataKeyVersionId: tea.String(dataKeyVersionId),
    })
    if err != nil {
        return nil, err
    }
    b64PlainDataKey := tea.StringValue(getResp.Body.Plaintext)
    plainDataKey, err := base64.StdEncoding.DecodeString(b64PlainDataKey)
    if err != nil {
        return nil, err
    }

    // Decrypt the data by using AES-GCM.
    block, err := aes.NewCipher(plainDataKey)
    if err != nil {
        return nil, err
    }
    gcm, err := cipher.NewGCM(block)
    if err != nil {
        return nil, err
    }
    nonceSize := gcm.NonceSize()
    if len(ciphertext) < nonceSize {
        return nil, fmt.Errorf("ciphertext too short")
    }

    nonce, ciphertext := ciphertext[:nonceSize], ciphertext[nonceSize:]
    return gcm.Open(nil, nonce, ciphertext, nil)
}

Schedule deletion

1. On the Data Keys tab, select the target KMS instance and click Schedule Deletion in the Actions column of the target data key.

2. In the dialog box, set the pending deletion period (7 to 30 days, default: 30 days) and click OK.

Cancel deletion

During the pending deletion period, you can cancel the deletion at any time to restore the data key to its normal state.

1. On the Data Keys tab, select the target KMS instance and find the data key in the pending deletion state.

2. Click Cancel Deletion in the Actions column of the target data key.

3. In the confirmation dialog box, click OK.