Client-Side Encryption

Always Encrypted

Client-side encryption (the Always Encrypted feature) lets us control keys and their access. The main benefit of it is that we can decide who can decrypt the data independently from their ability to access the container. On top of that, we can encrypt each property with different keys, which helps protect personally identifiable information (PII).

How it works

To encrypt our data, we need two different types of keys:

• Data encryption keys (DEKs):

  • Used to encrypt the data

  • Generated by us

  • Stored in the Cosmos DB database level (sharable between containers)

  • Can’t be rotated

  • Can’t control access

  • Encryption happens on Cosmos DB

• Customer-managed keys (CMKs):

  • Used to wrap the DEKs

  • Generated by us

  • Stored by us

  • Can be rotated

  • Can control access

  • Wrap happens in the SDK

Let’s see the process to start using the Always Encrypted feature. Everything has to be done through the SDK:

• We tell the SDK how to get CMKs.

• We generate a DEK wrapped with a CMK and store it in the database.

• We define an encryption policy, specifying the following:

  • The DEK to use

  • The CMK to use

  • The path to encrypt

  • The type of encryption

    • Deterministic: We get the same output every time for any given input. It’s needed to perform equality filters during a query, but it is easier to guess if there are few possible values.

    • Randomized: We get different outputs every time for any given input. It’s more secure, but we can’t use equality filters.

Even if there are more details to discuss on CMKs, this is all we need. Every time we store or read documents, they will be encrypted or decrypted based on our access to CMKs.

Note: Since each DEK is wrapped with a CMK, and we control access to CMKs, we indirectly control access to DEKs.

Customer-managed keys

While we have no control over DEKs other than their creation, we have total control over CMKs. We must create, store, secure, and feed them to the SDK. The easiest way to do so in Azure is through Key Vault.

First, we must create a new Key Vault instance and protect soft deleted keys from purging.