Data Encryption Key (DEK)

← Back to DP-420 Terminology Reference

Category: Maintenance & Security

Summary: for Always Encrypted in Azure Cosmos DB, you must use the Azure Cosmos DB SDK (C#, Java, or Node.js).

Overview

Here is the sequence to create and use a Data Encryption Key (DEK):

1. Create the Key Encryption Key (KEK): Before creating a DEK, you must create a master key in Azure Key Vault to protect it. Create a new RSA key in your vault, navigate to its current version, and copy the full Key Identifier (URI).
2. Grant the Client Application Access to the KEK: The application running the Cosmos DB SDK needs permission to wrap and unwrap the DEK. Assign your application's Managed Identity permissions to the Key Vault to grant Get, List, Wrap Key, Unwrap Key, Verify, and Sign access.
3. Initialize the Cosmos DB Client with a Key Resolver: In your application code, attach a Key Resolver to your Cosmos DB client instance so it can authenticate with Key Vault using the DefaultAzureCredential.

• • C#: Use KeyResolver and .WithEncryption() when building the CosmosClient.
  • Java: Use KeyEncryptionKeyClientBuilder.
  • JavaScript/TypeScript: Pass an AzureKeyVaultEncryptionKeyResolver into the clientEncryptionOptions.

1. Create the DEK via the SDK: Call the CreateClientEncryptionKey method on your Cosmos DB Database object, passing:

• • A unique string identifier for this DEK.
  • The encryption algorithm (AEAD_AES_256_CBC_HMAC_SHA256).
  • The KEK URI you copied in the first step.

1. Apply the DEK to a Container: When creating a new Cosmos DB container, define a ClientEncryptionPolicy. Specify which exact JSON properties should be encrypted, map them to your DEK's string identifier, and choose either Deterministic or Randomized encryption.

Once configured, your application will automatically request the wrapped DEK from Cosmos DB, decrypt it locally using Azure Key Vault, and seamlessly encrypt your properties before sending the data.

1. Create DEK

await database.CreateClientEncryptionKeyAsync(
    id: "dek1",
    encryptionAlgorithm:
        DataEncryptionKeyEncryptionAlgorithm
            .AeadAes256CbcHmacSha256,
    encryptionKeyWrapMetadata: metadata);

1. Use encryption

new CosmosClientBuilder(endpoint, credential)
    .WithEncryption(keyResolver, keyStoreProvider)
    .Build();

1. Create DEK

await database.CreateClientEncryptionKeyAsync(
    id: "dek1",
    encryptionAlgorithm:
        DataEncryptionKeyEncryptionAlgorithm
            .AeadAes256CbcHmacSha256,
    encryptionKeyWrapMetadata: metadata);

1. C# ClientEncryptionPolicy

ClientEncryptionPolicy encryptionPolicy =
    new ClientEncryptionPolicy(
        new List
        {
            new ClientEncryptionIncludedPath
            {
                Path = "/email",
                ClientEncryptionKeyId = "dek1",
                EncryptionType =
                    ClientEncryptionEncryptionType.Deterministic,
                EncryptionAlgorithm =
                    DataEncryptionKeyEncryptionAlgorithm
                        .AeadAes256CbcHmacSha256
            },
            new ClientEncryptionIncludedPath
            {
                Path = "/ssn",
                ClientEncryptionKeyId = "dek1",
                EncryptionType =
                    ClientEncryptionEncryptionType.Randomized,
                EncryptionAlgorithm =
                    DataEncryptionKeyEncryptionAlgorithm
                        .AeadAes256CbcHmacSha256
            }
        });


        ContainerProperties properties =
    new ContainerProperties(
        id: "Customers",
        partitionKeyPath: "/customerId");

properties.ClientEncryptionPolicy = encryptionPolicy;

await database.CreateContainerAsync(properties);

//If the policy contains: Plain Text
// /email -> Deterministic
// SELECT * FROM c WHERE c.email = "john@contoso.com"

1. Create DEK

CreateClientEncryptionKeyAsync()

1. Create KEK
2. Grant Key Vault permissions
3. Configure Cosmos Client
4. Create DEK
5. Create Encryption Policy
6. Create Container
7. Read/Write encrypted data

More Info & Links

• Microsoft Learn: Customer-managed keys

DP-420 Style Practice Questions

Q1. What is the main advantage of using customer-managed keys (CMK) over platform-managed keys?

• A. Full control over encryption key management, rotation, and revocation via Azure Key Vault
• B. Lower cost than platform-managed keys
• C. Elimination of the need to configure network access control
• D. Automatic multi-region writes

Q2. Where are customer-managed keys typically stored and managed for Azure Cosmos DB?

• A. Azure Key Vault
• B. Inside the Cosmos DB container itself
• C. In the application's source code
• D. In Azure Active Directory Connect

Answer Key

Answers are listed at the very end so you can attempt the questions first.

• Q1 (Customer-Managed Keys): A. Full control over encryption key management, rotation, and revocation via Azure Key Vault — CMK gives the customer control over key lifecycle management, useful for meeting specific compliance requirements.
• Q2 (Customer-Managed Keys): A. Azure Key Vault — Customer-managed keys are stored and managed in Azure Key Vault, which Azure Cosmos DB references for encryption operations.

---

DP-420: Designing and Implementing Cloud-Native Applications Using Microsoft Azure Cosmos DB — term detail page