Envelope Encryption with Alibaba Cloud

Skeleton scripts implementing envelope encryption and decryption with Alibaba Cloud's KMS.

Alibaba Cloud's Key Management Service (KMS)

Alibaba Cloud provides a professional, free and fully managed KMS that integrates with its other key services such as OSS (Alibaba Cloud's S3 offering) and RDS.

A top-level overview of Alibaba Cloud's KMS is available here (In English). Documentation for KMS API available here (in English)

As with other cloud providers, KMS revolves around a Customer Master Key (CMK). CMKs are created and managed by KMS and never exported from KMS. A CMK can be generated from the Cloud Management Console or by calling the relevant API. There are two options for generating CMKs in Alibaba Cloud:

Normal Key - where a CMK is generated by the KMS itself for you
External Key - where a user can import their own materials to generate the key, (read more here).

In these scripts, I've let KMS generate a CMK for me.

I haven't gotten around to experimenting with External Keys yet. External keys imported into Alibaba Cloud KMS must be symmetric keys (256 bit). The import of key materials appears very similar to the process in AWS's KMS.

Envelope Encryption

Like other vendors, Alibaba Cloud also offers an encryption mechanism known as Envelope Encryption. In brief, this involves encrypting/decrypting data using two levels of symmetric encryption keys, stored in two different locations.

Envelope Encryption is a strategy where a second set of encryption keys are generated, known as Data Keys. The Data Keys are in turn encrypted using a Master Key (the CMK). In addition to this, while Alibaba Cloud KMS generates these Data Keys for us, it does not store or manage them; that is left for the user to manage outside of the KMS. Only the Master Key is managed by Alibaba Cloud.

This approach attempts to offset some of the security and performance problems with using cloud services to directly encrypt/decrypt data.

How Envelope Encryption is Implemented in Alibaba Cloud

Performing Encryption:

Create a CMK and obtain the ID of the CMK;
Call KMS' GenerateDataKeyRequest() to generate Data Keys, passing the CMK's ID. Returns (in JSON or XML) plaintext Data Key and ciphertext Data Key (encrypted using the specified CMK);
By default Data Keys will be 256 bit AES. The set_KeySpec parameter can be used to change this. Options appear to be either AES_128 or AES_256 (using CBC block mode).
Use plaintext Data Key to encrypt your file locally, generating ciphertext version of the file;
Discard plaintext Data Key and flush from memory;
Save ciphertext Data Key and ciphertext file to persistent storage device or service.

Note: KMS only accepts calls via TLS as its returning the Data Key in plaintext as well as ciphertext forms. KMS doesn't retain any copy of the Data Key from this point on; we are on our own.

Performing Decryption:

Read ciphertext Data Key and ciphertext file from persistent storage device or service;
Call KMS' DecryptRequest() to decrypt the ciphertext Data Key (using the relevant CMK) and obtain plaintext Data Key;
Notably DecryptRequest() doesn't requires passing the ID of the CMK;
Use plaintext Data Key to decrypt the file locally;
Discard plaintext Data Key and flush from memory.

Optional Extras

I've also experimented with set_EncryptionContext(), which is essentially a hashing function providing additional Integrity and can be used with EncryptRequest() and GenerateDataKeyRequest(). I've experimented by passing a JSON array of key-value pairs containing meta-data about the document being encrypted. This acts as the Encryption Context. If using this option, the same context needs to be passed back to Alibaba Cloud's DecryptRequest() function. The encryption context does not need to remain secret and can be stored in plaintext alongside the ciphertext.

Prerequisites

The scripts are written in Python 2.7.

Requires the following Python modules installed if you don't already have them:

pip install json
pip install base64
pip install pycryptodome

PyCryptodome is a more recent incarnation of PyCrypto. It also neatly handles padding / unpadding required for AES-CBC.

The required components of the Alibaba Cloud SDK can also be installed as follows:

pip install aliyun-python-sdk-core, aliyun-python-sdk-kms

Note: An AccessKey will also be required. An Access Key (KeyID and KeySecret) can easily be generated from the Alibaba Cloud Management Console, configuring a new user within RAM and assigning an Access Key to that user.

Running the Scripts

Assigned AccessKey, Region and CMK_ID details are held in credentials.py.

KMS is region-specific. This means that a CMK created in cn-beijing can only be used with Alibaba Cloud services running in that region. Other CMKs would need to be created and managed for separate regions. KMS allows users to create up to 200 different CMKs per region.

Usage Example:

These scripts demonstrate the basic use of envelope encryption for file-level encryption. Encrypted files could then be uploaded to a service such as Alibaba Cloud's OSS.

The envelope encryption and decryption scripts can be called as follows, passing in file paths for the input plaintext data file to be encrypted/decrypted and a file path for storing the resulting plaintext/ciphertext output:

>$ python aliEncrypt.py data/alice_in_wonderland.txt test/ciphertext.txt
>$ python aliDecrypt.py test/ciphertext.txt test/plaintext.txt
>$ diff data/alice_in_wonderland.txt test/plaintext.txt

Security

KMS uses Alibaba Cloud's Resource Access Management (RAM) to control access to all KMS resources.

For this application I created a new RAM User with its own AccessKey for API access. Varying authorisation policies can be assigned to RAM Users (and Groups), with policies representing a set of permissions being granted to the user.

I created a Custom Policy, as shown below, restricting access to specific KMS functions and use of a specific CMK. Access to a specific resource can also be configured using Alibaba Resource Number (ARN) identifiers.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
          "kms:Encrypt",
          "kms:Decrypt",
          "kms:GenerateDataKey"
      ],
      "Resource": [ "acs:kms:cn-beijing:${account}:key/${key-id}" ]
    }
  ]
}

It's also possible to tag KMS resources and configure access policies based on tagging.

Other Usage Information

I've tested this via a KMS running in the cn-beijing region. According to the documentation, Alibaba Cloud's KMS has multi-region support and also covers endpoints outside of mainland China.

To Do

Experiment with generating External Key type CMKs.
Experiment with Alibaba Cloud's Security Token Service (STS), using temporary access tokens and removing need for users to manage and secure long-term AccessKey credentials.

Built With

Authors

Andrew Houlbrook - Initial work - andrewhoulbrook

License

This project is licensed under the MIT License - see the LICENSE.md file for details

netsec / alicloud-envelope-encryption