All Products
Document Center

Key Management Service:Use envelope encryption to encrypt and decrypt local data

Last Updated:Jun 04, 2024

You must encrypt sensitive information in your IT assets that are deployed on Alibaba Cloud. If you need to encrypt a large amount of local data, you can call cryptographic API operations of Key Management Service (KMS) to generate a data key online and then use the data key to encrypt the local data offline. This encryption mechanism is known as envelope encryption.

Background information

You can use envelope encryption in, but not limited to, the following scenarios:

  • Encrypt business data files.

  • Encrypt all data stored on local disks.

This topic describes how to use envelope encryption to encrypt and decrypt local files.

How data encryption and decryption work

Use KMS to create a customer master key (CMK), use the CMK to generate a data key, and then use the data key to encrypt and decrypt local files. Envelope encryption is suitable for encrypting and decrypting a large amount of data. The following figure shows the procedure of envelope encryption.

  • Envelope encryption信封加密Procedure:

    1. Create a CMK in the KMS console or by calling the CreateKey operation.

    2. Call the GenerateDataKey operation to generate a data key. KMS returns the plaintext and ciphertext of the data key.

    3. Use the plaintext data key to encrypt the local files and then delete the plaintext data key from the memory.

    4. Store the ciphertext data key and encrypted data files on a persistent storage device or service.

  • Envelope decryption 信封解密Procedure :

    1. Retrieve the ciphertext data key from the local files.

    2. Call the Decrypt operation of KMS to decrypt the ciphertext data key. The plaintext of the data key is returned.

    3. Use the plaintext data key to decrypt the local files and then delete the plaintext data key from the memory.

Encryption and decryption API operations

You can call the API operations described in the following table to encrypt and decrypt local data.

API operation



Creates a CMK.


Creates an alias for a CMK.


Generates a data key and uses the specified CMK to encrypt the data key. KMS returns the plaintext and ciphertext of the data key.


Decrypts data that is encrypted in KMS, including the ciphertext data key generated by calling the GenerateDataKey operation. You do not need to specify a CMK.

Encrypt and decrypt local files


The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using the AccessKey pair to perform operations is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. We recommend that you do not save the AccessKey ID and AccessKey Secret in your project code. Otherwise, the AccessKey pair may be leaked and the security of all the resources that belong to your account may be compromised.

In this example, the AccessKey pair is saved in ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables to implement identity authentication. For more information about how to configure authentication information, see Instantiate a client and configure a credential.

You can create a CMK and encrypt and decrypt local files by using Alibaba Cloud CLI.

  1. Call the CreateKey operation to create a CMK.

    aliyun kms CreateKey

    Expected output:

      "KeyMetadata": {
        "CreationDate": "2019-04-08T07:45:54Z",
        "Description": "",
        "KeyId": "1234abcd-12ab-34cd-56ef-12345678****",
        "KeyState": "Enabled",
        "KeyUsage": "ENCRYPT/DECRYPT",
        "DeleteDate": "",
        "Creator": "151266687691****",
        "Arn": "acs:kms:cn-hangzhou:151266687691****:key/1234abcd-12ab-34cd-56ef-12345678****",
        "Origin": "Aliyun_KMS",
        "MaterialExpireTime": ""
      "RequestId": "2a37b168-9fa0-4d71-aba4-2077dd9e80df"
  2. Optional. Create an alias for the CMK.

    Aliases are optionally used to identify CMKs. If a CMK does not have an alias, you can use the ID of the CMK to identify the CMK.

    aliyun kms CreateAlias --AliasName alias/Apollo/WorkKey --KeyId 1234abcd-12ab-34cd-56ef-12345678****

    In this example, Apollo/WorkKey is the alias of the CMK in the Apollo project. You can use the alias alias/Apollo/WorkKey in subsequent sample code to call the Encrypt operation.

  3. Encrypt a local file.

    In the following sample code:

    • alias/Apollo/WorkKey is the alias of the CMK.

    • ./data/sales.csv is the plaintext file.

    • ./data/sales.csv.cipher is the returned ciphertext file.

    #!/usr/bin/env python
    import json
    import base64
    from Crypto.Cipher import AES
    from aliyunsdkcore import client
    from aliyunsdkkms.request.v20160120 import GenerateDataKeyRequest
    def KmsGenerateDataKey(client, key_alias):
        request = GenerateDataKeyRequest.GenerateDataKeyRequest()
        response = json.loads(client.do_action(request))
        datakey_encrypted = response["CiphertextBlob"]
        datakey_plaintext = response["Plaintext"]
        return (datakey_plaintext, datakey_encrypted)
    def ReadTextFile(in_file):
      file = open(in_file, 'r')
      content =
      return content
    def WriteTextFile(out_file, lines):
      file = open(out_file, 'w')
      for ln in lines:
    # Out file format (text)
    # Line 1: b64 encoded data key
    # Line 2: b64 encoded IV
    # Line 3: b64 encoded ciphertext
    # Line 4: b64 encoded authentication tag
    def LocalEncrypt(datakey_plaintext, datakey_encrypted, in_file, out_file):
      data_key_binary = base64.b64decode(datakey_plaintext)
      cipher =, AES.MODE_EAX)
      in_content = ReadTextFile(in_file)
      ciphertext, tag = cipher.encrypt_and_digest(in_content)
      lines = [datakey_encrypted, base64.b64encode(cipher.nonce), base64.b64encode(ciphertext), base64.b64encode(tag)];
      WriteTextFile(out_file, lines)
    clt = client.AcsClient(os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),'Region-Id')
    key_alias = 'alias/Apollo/WorkKey'
    in_file = './data/sales.csv'
    out_file = './data/sales.csv.cipher'
    # Generate Data Key
    datakey = KmsGenerateDataKey(clt, key_alias)
    # Locally Encrypt the sales record
    LocalEncrypt(datakey[0], datakey[1], in_file, out_file)
  4. Decrypt a local file.

    In the following sample code:

    • ./data/sales.csv.cipher is the ciphertext file.

    • ./data/decrypted_sales.csv is the returned plaintext file.

    #!/usr/bin/env python
    import json
    import base64
    from Crypto.Cipher import AES
    from aliyunsdkcore import client
    from aliyunsdkkms.request.v20160120 import DecryptRequest
    def KmsDecrypt(client, ciphertext):
      request = DecryptRequest.DecryptRequest()
      response = json.loads(client.do_action(request))
      return response.get("Plaintext")
    def ReadTextFile(in_file):
      file = open(in_file, 'r')
      lines = []
      for ln in file:
      return lines
    def WriteTextFile(out_file, content):
      file = open(out_file, 'w')
    def LocalDecrypt(datakey, iv, ciphertext, tag, out_file):
      cipher =, AES.MODE_EAX, iv)
      data = cipher.decrypt_and_verify(ciphertext, tag).decode('utf-8')
      WriteTextFile(out_file, data)
    clt = client.AcsClient(os.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),os.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),'Region-Id')
    in_file = './data/sales.csv.cipher'
    out_file = './data/decrypted_sales.csv'
    # Read encrypted file
    in_lines = ReadTextFile(in_file)
    # Decrypt data key
    datakey = KmsDecrypt(clt, in_lines[0])
    # Locally decrypt the sales record
      base64.b64decode(in_lines[1]), # IV
      base64.b64decode(in_lines[2]), # Ciphertext
      base64.b64decode(in_lines[3]), # Authentication tag