If client-side encryption is performed, objects are encrypted on the local client before they are uploaded to OSS. This topic describes how to perform client-side encryption.

Disclaimer

  • When you use client-side encryption, you must ensure the integrity and validity of the CMK. If the CMK is incorrectly used or lost due to improper maintenance, you will be held responsible for all losses and consequences caused by decryption failures.
  • When you copy or migrate encrypted data, you must ensure the integrity and validity of the encrypted metadata. If the encrypted metadata is incorrectly used or lost due to improper maintenance, you will be held responsible for all losses and consequences caused by decryption failures.

Implementation methods

OSS provides the following SDKs to implement client-side encryption:

Background information

In client-side encryption, a random data key is generated for each object to perform symmetric encryption on the object. The client uses a CMK to encrypt the random data key. The encrypted data key is uploaded as a part of the object metadata and stored in the OSS server. When an object is downloaded, the client uses the CMK to decrypt the random data key and then uses the data key to decrypt the object. The CMK is used only on the client and is not transmitted over the network or stored in the server, which secures data.
Note
  • Client-side encryption can be performed only on objects smaller than 5 GB. Generic texts or byte streams can be encrypted.
  • After performing client-side encryption on an object and uploading the object, do not call update_object_meta or CopyObject provided by the OSS SDK for Python to modify the object metadata.
You can use CMKs managed in either of the following ways:

For the complete sample code, visit GitHub.

Use CMKs managed by KMS

If you use CMKs managed by KMS for client-side encryption, you need only to specify the CMK ID when uploading objects instead of providing the client with a data key. The following figure shows the encryption process in detail.key2
  • Encrypt and upload an object
    1. Obtain a data key.

      The client uses a specified CMK ID to request a data key used to encrypt the object from KMS. KMS returns a random data key and an encrypted data key.

    2. Encrypt the object and upload it to OSS.

      The client uses the returned data key to encrypt the object and uploads the encrypted object and encrypted data key to OSS.

  • Download and decrypt an object
    1. Download an object.

      The client downloads an encrypted object. The encrypted data key is included in the metadata of the object.

    2. Decrypt the object.

      The client sends the encrypted data key and the corresponding CMK ID to KMS. KMS uses the CMK sent by the client to decrypt the encrypted data key and returns the decrypted data key to the client.

Note
  • The client obtains a unique data key for each object to upload.
  • To ensure data security, we recommend that you rotate or update the CMK regularly.
  • You must maintain the mapping relationship between the CMKs and the encrypted objects.

Use CMKs managed by yourself

To use this method for client-side encryption, you must generate and manage CMKs by yourself. When you perform client-side encryption on an object to upload, you must upload a symmetric or asymmetric CMK to the client. The following figure shows the encryption process in detail.key3
  • Encrypt and upload an object
    1. You must provide the client with a symmetric or asymmetric CMK.
    2. The client uses the CMK to generate a symmetric data key that is used only to encrypt the current object to upload. The client generates a random and unique data key for each object to upload.
    3. The client uses the data key to encrypt the object to upload and uses the CMK to encrypt the data key.
    4. The encrypted data key is included in the metadata of the uploaded object.
  • Download and decrypt an object
    1. The client downloads an encrypted object. The encrypted data key is included in the metadata of the object.
    2. By using the materials in the object metadata, the client determines the CMK used to generate the data key and uses this CMK to decrypt the encrypted data key. Then, the client uses the decrypted data key to decrypt the object.
Notice
  • CMKs and unencrypted data are not sent to OSS. Therefore, keep your CMKs secure. If a CMK is lost, objects encrypted by using the data keys generated with this CMK cannot be decrypted.
  • Data keys are randomly generated by the client.