針對 Azure Cosmos DB，用戶端加密與 Always Encrypted 一起使用

若要使用 Always Encrypted，必須將 KeyResolver 的執行個體連結至 Azure Cosmos DB SDK 執行個體。 此類別定義於 Azure.Security.KeyVault.Keys.Cryptography 命名空間之中，用來與裝載 CMK 的金鑰存放區進行互動。

下列程式碼片段會使用 DefaultAzureCredential 類別來取得存取 Azure Key Vault 執行個體時所要使用的 Microsoft Entra 身分識別。 您可以在此找到建立各種不同 TokenCredential 類別的範例。

var tokenCredential = new DefaultAzureCredential();
var keyResolver = new KeyResolver(tokenCredential);
var client = new CosmosClient("<connection-string>")
    .WithEncryption(keyResolver, KeyEncryptionKeyResolverName.AzureKeyVault);

若要使用 Always Encrypted，必須將 KeyEncryptionKeyClientBuilder 的執行個體連結至 Azure Cosmos DB SDK 執行個體。 此類別定義於 com.azure.security.keyvault.keys.cryptography 命名空間之中，用來與裝載 CMK 的金鑰存放區進行互動。

下列程式碼片段會使用 DefaultAzureCredential 類別來取得存取 Azure Key Vault 執行個體時所要使用的 Microsoft Entra 身分識別。 您可以在此找到建立各種不同 TokenCredential 類別的範例。

TokenCredential tokenCredential = new DefaultAzureCredentialBuilder()
    .build();
KeyEncryptionKeyClientBuilder keyEncryptionKeyClientBuilder =
    new KeyEncryptionKeyClientBuilder().credential(tokenCredentials);
CosmosAsyncClient client = new CosmosClientBuilder()
    .endpoint("<endpoint>")
    .key("<primary-key>")
    .buildAsyncClient();
CosmosEncryptionAsyncClient cosmosEncryptionAsyncClient =
    new CosmosEncryptionClientBuilder().cosmosAsyncClient(client).keyEncryptionKeyResolver(keyEncryptionKeyClientBuilder)
        .keyEncryptionKeyResolverName(CosmosEncryptionClientBuilder.KEY_RESOLVER_NAME_AZURE_KEY_VAULT).buildAsyncClient();

建立新的資料加密金鑰是透過呼叫 CreateClientEncryptionKeyAsync 方法並傳遞來完成：

• 用於資料庫中唯一識別金鑰的字串識別碼。
• 要與金鑰搭配使用的加密演算法。 目前只支援一種演算法。
• Azure Key Vault 中所儲存 CMK 的金鑰識別碼。 此參數會傳遞至泛型 EncryptionKeyWrapMetadata 物件，其中：
  • type 定義金鑰解析程式 (例如 Azure Key Vault)。
  • name 可以是您想要的任何易記名稱。
  • value 必須是金鑰識別碼。

  重要

  金鑰建立後，請瀏覽至其目前的版本，並複製其完整的金鑰識別碼：https://<my-key-vault>.vault.azure.net/keys/<key>/<version>。 如果您省略金鑰識別碼結尾的金鑰版本，則會使用最新版的金鑰。

  • algorithm 定義應使用哪一種演算法搭配客戶自控金鑰來包裝重要的加密金鑰。

var database = client.GetDatabase("my-database");
await database.CreateClientEncryptionKeyAsync(
    "my-key",
    DataEncryptionAlgorithm.AeadAes256CbcHmacSha256,
    new EncryptionKeyWrapMetadata(
        KeyEncryptionKeyResolverName.AzureKeyVault,
        "akvKey",
        "https://<my-key-vault>.vault.azure.net/keys/<key>/<version>",
        EncryptionAlgorithm.RsaOaep.ToString()));

建立新的資料加密金鑰是透過呼叫 createClientEncryptionKey 方法並傳遞來完成：

• 用於資料庫中唯一識別金鑰的字串識別碼。
• 要與金鑰搭配使用的加密演算法。 目前只支援一種演算法。
• Azure Key Vault 中所儲存 CMK 的金鑰識別碼。 此參數會傳遞至泛型 EncryptionKeyWrapMetadata 物件，其中：
  • type 定義金鑰解析程式 (例如 Azure Key Vault)。
  • name 可以是您想要的任何易記名稱。
  • value 必須是金鑰識別碼。

  重要

  金鑰建立後，請瀏覽至其目前的版本，並複製其完整的金鑰識別碼：https://<my-key-vault>.vault.azure.net/keys/<key>/<version>。 如果您省略金鑰識別碼結尾的金鑰版本，則會使用最新版的金鑰。

  • algorithm 定義應使用哪一種演算法搭配客戶自控金鑰來包裝重要的加密金鑰。

CosmosEncryptionAsyncDatabase database =
    cosmosEncryptionAsyncClient.getCosmosEncryptionAsyncDatabase("my-database");
EncryptionKeyWrapMetadata metadata = new EncryptionKeyWrapMetadata(
    cosmosEncryptionAsyncClient.getKeyEncryptionKeyResolverName(), 
    "akvKey", 
    "https://<my-key-vault>.vault.azure.net/keys/<key>/<version>",
    EncryptionAlgorithm.RSA_OAEP.toString());
database.createClientEncryptionKey(
    "my-key",
    CosmosEncryptionAlgorithm.AEAD_AES_256_CBC_HMAC_SHA256.getName(),
    metadata);

var path1 = new ClientEncryptionIncludedPath
{
    Path = "/property1",
    ClientEncryptionKeyId = "my-key",
    EncryptionType = EncryptionType.Deterministic.ToString(),
    EncryptionAlgorithm = DataEncryptionAlgorithm.AeadAes256CbcHmacSha256
};
var path2 = new ClientEncryptionIncludedPath
{
    Path = "/property2",
    ClientEncryptionKeyId = "my-key",
    EncryptionType = EncryptionType.Randomized.ToString(),
    EncryptionAlgorithm = DataEncryptionAlgorithm.AeadAes256CbcHmacSha256
};
await database.DefineContainer("my-container", "/partition-key")
    .WithClientEncryptionPolicy()
    .WithIncludedPath(path1)
    .WithIncludedPath(path2)
    .Attach()
    .CreateAsync();

ClientEncryptionIncludedPath path1 = new ClientEncryptionIncludedPath();
path1.setClientEncryptionKeyId("my-key"):
path1.setPath("/property1");
path1.setEncryptionType(CosmosEncryptionType.DETERMINISTIC.getName());
path1.setEncryptionAlgorithm(CosmosEncryptionAlgorithm.AEAES_256_CBC_HMAC_SHA_256.getName());

ClientEncryptionIncludedPath path2 = new ClientEncryptionIncludedPath();
path2.setClientEncryptionKeyId("my-key"):
path2.setPath("/property2");
path2.setEncryptionType(CosmosEncryptionType.RANDOMIZED.getName());
path2.setEncryptionAlgorithm(CosmosEncryptionAlgorithm.AEAES_256_CBC_HMAC_SHA_256.getName());

List<ClientEncryptionIncludedPath> paths = new ArrayList<>();
paths.add(path1);
paths.add(path2);

CosmosContainerProperties containerProperties =
    new CosmosContainerProperties("my-container", "/id");
containerProperties.setClientEncryptionPolicy(new ClientEncryptionPolicy(paths));
database.createEncryptionContainerAsync(containerProperties);

var queryDefinition = container.CreateQueryDefinition(
    "SELECT * FROM c where c.property1 = @Property1");
await queryDefinition.AddParameterAsync(
    "@Property1",
    1234,
    "/property1");

SqlQuerySpecWithEncryption sqlQuerySpecWithEncryption = new SqlQuerySpecWithEncryption(
    new SqlQuerySpec("SELECT * FROM c where c.property1 = @Property1"));
sqlQuerySpecWithEncryption.addEncryptionParameter(
    "/property1", new SqlParameter("@Property1", 1234))

await database.RewrapClientEncryptionKeyAsync(
    "my-key",
    new EncryptionKeyWrapMetadata(
        KeyEncryptionKeyResolverName.AzureKeyVault,
        "akvKey",
        "https://<my-key-vault>.vault.azure.net/keys/<new-key>/<version>",
        EncryptionAlgorithm.RsaOaep.ToString()));

EncryptionKeyWrapMetadata metadata = new EncryptionKeyWrapMetadata(
    cosmosEncryptionAsyncClient.getKeyEncryptionKeyResolverName(), 
    "akvKey", 
    "https://<my-key-vault>.vault.azure.net/keys/<new-key>/<version>",
    EncryptionAlgorithm.RSA_OAEP.toString());
database.rewrapClientEncryptionKey(
    "my-key",
    metadata);