使用 Azure Key Vault 为 Azure Cosmos 帐户配置客户管理的密钥Configure customer-managed keys for your Azure Cosmos account with Azure Key Vault

适用于: SQL API Cassandra API Gremlin API 表 API Azure Cosmos DB API for MongoDB

存储在 Azure Cosmos 帐户中的数据会使用 Azure 托管密钥(服务托管密钥)自动无缝地进行加密。Data stored in your Azure Cosmos account is automatically and seamlessly encrypted with keys managed by Azure (service-managed keys). 还可以选择使用你自己托管的密钥(客户托管密钥)来添加另一个加密层。Optionally, you can choose to add a second layer of encryption with keys you manage (customer-managed keys).

围绕客户数据的加密层

必须将客户托管密钥存储在 Azure Key Vault 中,并为每个启用了客户托管密钥的 Azure Cosmos 帐户提供一个密钥。You must store customer-managed keys in Azure Key Vault and provide a key for each Azure Cosmos account that is enabled with customer-managed keys. 此密钥用于加密存储在该帐户中的所有数据。This key is used to encrypt all the data stored in that account.

备注

当前,客户托管密钥仅适用于新的 Azure Cosmos 帐户。Currently, customer-managed keys are available only for new Azure Cosmos accounts. 应在创建帐户期间配置这些密钥。You should configure them during account creation.

为 Azure 订阅注册 Azure Cosmos DB 资源提供程序Register the Azure Cosmos DB resource provider for your Azure subscription

  1. 登录到 Azure 门户,转到 Azure 订阅,并在 “设置” 选项卡下选择 “资源提供程序”Sign in to the Azure portal, go to your Azure subscription, and select Resource providers under the Settings tab:

    左侧菜单中的“资源提供程序”项

  2. 搜索“Microsoft DocumentDB”资源提供程序。Search for the Microsoft.DocumentDB resource provider. 确认该资源提供程序是否标记为已注册。Verify if the resource provider is already marked as registered. 如果不是,请选择该资源提供程序,然后选择“注册”:If not, choose the resource provider and select Register:

    注册“Microsoft DocumentDB”资源提供程序

配置 Azure Key Vault 实例Configure your Azure Key Vault instance

将客户管理的密钥与 Azure Cosmos DB 结合使用时,需要在计划用于托管加密密钥的 Azure Key Vault 实例上设置两个属性: “软删除”“清除保护”Using customer-managed keys with Azure Cosmos DB requires you to set two properties on the Azure Key Vault instance that you plan to use to host your encryption keys: Soft Delete and Purge Protection.

如果创建新的 Azure Key Vault 实例,请在创建过程中启用以下属性:If you create a new Azure Key Vault instance, enable these properties during creation:

为新的 Azure Key Vault 实例启用“软删除”和“清除保护”

如果使用的是现有 Azure Key Vault 实例,则可以通过查看 Azure 门户中的“属性”部分来验证是否已启用这些属性。If you're using an existing Azure Key Vault instance, you can verify that these properties are enabled by looking at the Properties section on the Azure portal. 如果未启用任一属性,请参阅以下文章中的“启用软删除”和“启用清除保护”部分:If any of these properties isn't enabled, see the "Enabling soft-delete" and "Enabling Purge Protection" sections in one of the following articles:

将访问策略添加到 Azure Key Vault 实例Add an access policy to your Azure Key Vault instance

  1. 在 Azure 门户中,转到你打算用来托管加密密钥的 Azure Key Vault 实例。From the Azure portal, go to the Azure Key Vault instance that you plan to use to host your encryption keys. 在左侧菜单中选择“访问策略”:Select Access Policies from the left menu:

    左侧菜单中的“访问策略”

  2. 选择“+ 添加访问策略”。Select + Add Access Policy.

  3. 在“密钥权限”下拉菜单中,选择“获取”、“解包密钥”和“包装密钥”权限: Under the Key permissions drop-down menu, select Get , Unwrap Key , and Wrap Key permissions:

    选择适当的权限

  4. 在“选择主体”下,选择“未选择任何项”。 Under Select principal, select None selected. 然后,搜索“Azure Cosmos DB”主体并将其选中(为了便于查找,对于 Azure 中国区域,还可以按主体 ID a232010e-820c-4083-83bb-3ace5fc29d0b 进行搜索)。Then, search for Azure Cosmos DB principal and select it (to make it easier to find, you can also search by principal ID: a232010e-820c-4083-83bb-3ace5fc29d0b for azure Azure China regions). 最后,选择底部的“选择”。Finally, choose Select at the bottom. 如果列表中没有“Azure Cosmos DB”主体,可能需要根据本文的注册资源提供程序部分所述,重新注册 Microsoft.DocumentDB 资源提供程序)。If the Azure Cosmos DB principal isn't in the list, you might need to re-register the Microsoft.DocumentDB resource provider as described in the Register the resource provider section of this article.

    选择 Azure Cosmos DB 主体

  5. 选择“添加”以添加新的访问策略。Select Add to add the new access policy.

  6. 在密钥保管库实例上选择“保存”,以保存所有更改。Select Save on the Key Vault instance to save all changes.

在 Azure Key Vault 中生成密钥Generate a key in Azure Key Vault

  1. 在 Azure 门户中,转到你打算用来托管加密密钥的 Azure Key Vault 实例。From the Azure portal, go the Azure Key Vault instance that you plan to use to host your encryption keys. 然后,从左侧菜单中选择“密钥”:Then, select Keys from the left menu:

    左侧菜单中的“密钥”项

  2. 选择“生成/导入”,为新密钥提供名称,并选择一个 RSA 密钥大小。Select Generate/Import, provide a name for the new key, and select an RSA key size. 建议至少使用 3072,以获得最佳安全性。A minimum of 3072 is recommended for best security. 然后选择“创建”:Then select Create:

    新建密钥

  3. 创建密钥后,选择新创建的密钥,然后选择其当前版本。After the key is created, select the newly created key and then its current version.

  4. 复制密钥的密钥标识符(最后一个正斜杠之后的部分除外):Copy the key's Key Identifier, except the part after the last forward slash:

    复制密钥的密钥标识符

创建新的 Azure Cosmos 帐户Create a new Azure Cosmos account

使用 Azure 门户Using the Azure portal

当你从 Azure 门户创建新的 Azure Cosmos DB 帐户时,请选择“加密”步骤中“客户管理的密钥”。When you create a new Azure Cosmos DB account from the Azure portal, choose Customer-managed key in the Encryption step. 在“密钥 URI”字段中,粘贴从上一步复制的 Azure Key Vault 密钥的 URI/密钥标识符:In the Key URI field, paste the URI/key identifier of the Azure Key Vault key that you copied from the previous step:

在 Azure 门户中设置 CMK 参数

使用 Azure PowerShellUsing Azure PowerShell

使用 PowerShell 创建新的 Azure Cosmos DB 帐户时:When you create a new Azure Cosmos DB account with PowerShell:

  • 在“PropertyObject”中,传递前面在“keyVaultKeyUri”属性下复制的 Azure Key Vault 密钥的 URI。Pass the URI of the Azure Key Vault key copied earlier under the keyVaultKeyUri property in PropertyObject.

  • 使用 2019-12-12 或更高版本作为 API 版本。Use 2019-12-12 or later as the API version.

重要

必须显式设置 locations 属性,才能通过客户管理的密钥成功创建帐户。You must set the locations property explicitly for the account to be successfully created with customer-managed keys.

$resourceGroupName = "myResourceGroup"
$accountLocation = "China North 2"
$accountName = "mycosmosaccount"

$failoverLocations = @(
    @{ "locationName"="China North 2"; "failoverPriority"=0 }
)

$CosmosDBProperties = @{
    "databaseAccountOfferType"="Standard";
    "locations"=$failoverLocations;
    "keyVaultKeyUri" = "https://<my-vault>.vault.azure.cn/keys/<my-key>";
}

New-AzResource -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    -ApiVersion "2019-12-12" -ResourceGroupName $resourceGroupName `
    -Location $accountLocation -Name $accountName -PropertyObject $CosmosDBProperties

创建帐户后,可以通过提取 Azure Key Vault 密钥的 URI 来验证是否已启用客户管理的密钥:After the account has been created, you can verify that customer-managed keys have been enabled by fetching the URI of the Azure Key Vault key:

Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
    -ResourceType "Microsoft.DocumentDb/databaseAccounts" `
    | Select-Object -ExpandProperty Properties `
    | Select-Object -ExpandProperty keyVaultKeyUri

使用 Azure 资源管理器模板Using an Azure Resource Manager template

通过 Azure 资源管理器模板创建新的 Azure Cosmos 帐户时:When you create a new Azure Cosmos account through an Azure Resource Manager template:

  • 在“属性”对象中,传递前面在“keyVaultKeyUri”属性下复制的 Azure Key Vault 密钥的 URI。Pass the URI of the Azure Key Vault key that you copied earlier under the keyVaultKeyUri property in the properties object.

  • 使用 2019-12-12 或更高版本作为 API 版本。Use 2019-12-12 or later as the API version.

重要

必须显式设置 locations 属性,才能通过客户管理的密钥成功创建帐户。You must set the locations property explicitly for the account to be successfully created with customer-managed keys.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "accountName": {
            "type": "string"
        },
        "location": {
            "type": "string"
        },
        "keyVaultKeyUri": {
            "type": "string"
        }
    },
    "resources": 
    [
        {
            "type": "Microsoft.DocumentDB/databaseAccounts",
            "name": "[parameters('accountName')]",
            "apiVersion": "2019-12-12",
            "kind": "GlobalDocumentDB",
            "location": "[parameters('location')]",
            "properties": {
                "locations": [ 
                    {
                        "locationName": "[parameters('location')]",
                        "failoverPriority": 0,
                        "isZoneRedundant": false
                    }
                ],
                "databaseAccountOfferType": "Standard",
                "keyVaultKeyUri": "[parameters('keyVaultKeyUri')]"
            }
        }
    ]
}

使用以下 PowerShell 脚本部署模板:Deploy the template with the following PowerShell script:

$resourceGroupName = "myResourceGroup"
$accountName = "mycosmosaccount"
$accountLocation = "China North 2"
$keyVaultKeyUri = "https://<my-vault>.vault.azure.cn/keys/<my-key>"

New-AzResourceGroupDeployment `
    -ResourceGroupName $resourceGroupName `
    -TemplateFile "deploy.json" `
    -accountName $accountName `
    -location $accountLocation `
    -keyVaultKeyUri $keyVaultKeyUri

使用 Azure CLIUsing the Azure CLI

通过 Azure CLI 创建新的 Azure Cosmos 帐户时,传递前面在 --key-uri 参数下复制的 Azure Key Vault 密钥的 URI。When you create a new Azure Cosmos account through the Azure CLI, pass the URI of the Azure Key Vault key that you copied earlier under the --key-uri parameter.

resourceGroupName='myResourceGroup'
accountName='mycosmosaccount'
keyVaultKeyUri = 'https://<my-vault>.vault.azure.cn/keys/<my-key>'

az cosmosdb create \
    -n $accountName \
    -g $resourceGroupName \
    --locations regionName='China North 2' failoverPriority=0 isZoneRedundant=False \
    --key-uri $keyVaultKeyUri

创建帐户后,可以通过提取 Azure Key Vault 密钥的 URI 来验证是否已启用客户管理的密钥:After the account has been created, you can verify that customer-managed keys have been enabled by fetching the URI of the Azure Key Vault key:

az cosmosdb show \
    -n $accountName \
    -g $resourceGroupName \
    --query keyVaultKeyUri

密钥轮换Key rotation

可以通过两种方式来轮换 Azure Cosmos 帐户使用的客户托管密钥。Rotating the customer-managed key used by your Azure Cosmos account can be done in two ways.

  • 创建当前在 Azure Key Vault 中使用的密钥的新版本:Create a new version of the key currently used from Azure Key Vault:

    创建新的密钥版本

  • 通过更新帐户的密钥 URI,将当前使用的密钥与完全不同的密钥交换。Swap the key currently used with a totally different one by updating the key URI on your account. 在 Azure 门户中转到你的 Azure Cosmos 帐户,然后在左侧菜单中选择“数据加密”:From the Azure portal, go to your Azure Cosmos account and select Data Encryption from the left menu:

    “数据加密”菜单项

    然后,将“密钥 URI”替换为要使用的新密钥,并选择“保存”:Then, replace the Key URI with the new key you want to use and select Save:

    更新密钥 URI

    下面介绍如何在 PowerShell 中实现相同的结果:Here's how to do achieve the same result in PowerShell:

    $resourceGroupName = "myResourceGroup"
    $accountName = "mycosmosaccount"
    $newKeyUri = "https://<my-vault>.vault.azure.cn/keys/<my-new-key>"
    
    $account = Get-AzResource -ResourceGroupName $resourceGroupName -Name $accountName `
        -ResourceType "Microsoft.DocumentDb/databaseAccounts"
    
    $account.Properties.keyVaultKeyUri = $newKeyUri
    
    $account | Set-AzResource -Force
    

可以在 24 小时后禁用以前的密钥或密钥版本,也可以在 Azure Key Vault 审核日志不再显示该密钥或密钥版本 Azure Cosmos DB 中的活动之后禁用。The previous key or key version can be disabled after 24 hours, or after the Azure Key Vault audit logs don't show activity from Azure Cosmos DB on that key or key version anymore.

错误处理。Error handling

在 Azure Cosmos DB 中使用客户托管密钥 (CMK) 时,如果存在任何错误,Azure Cosmos DB 会在响应中返回错误详细信息以及 HTTP 子状态代码。When using Customer-Managed Keys (CMK) in Azure Cosmos DB, if there are any errors, Azure Cosmos DB returns the error details along with a HTTP sub-status code in the response. 可以使用此子状态代码来调试问题的根本原因。You can use this sub-status code to debug the root cause of the issue. 请参阅 Azure Cosmos DB 的 HTTP 状态代码一文获取支持的 HTTP 子状态代码的列表。See the HTTP Status Codes for Azure Cosmos DB article to get the list of supported HTTP sub-status codes.

常见问题Frequently asked questions

启用客户管理的密钥是否额外收费?Is there an additional charge to enable customer-managed keys?

否,启用此功能不收取任何费用。No, there's no charge to enable this feature.

客户管理的密钥会对容量计划产生怎样的影响?How do customer-managed keys impact capacity planning?

使用客户管理的密钥时,数据库操作使用的请求单位会增加,以反映执行加密和解密数据所需的额外处理。When using customer-managed keys, Request Units consumed by your database operations see an increase to reflect the additional processing required to perform encryption and decryption of your data. 这可能会导致预配容量的利用率略高。This may lead to slightly higher utilization of your provisioned capacity. 请参阅下表中的指南:Use the table below for guidance:

操作类型Operation type 请求单位增加Request Unit increase
点读取(按 ID 获取项)Point-reads (fetching items by their ID) 每个操作 + 5%+ 5% per operation
任何写入操作Any write operation 每个操作 + 6%+ 6% per operation
每个索引属性约为 + 0.06 RUapprox. + 0.06 RU per indexed property
查询、读取更改源或冲突源Queries, reading change feed, or conflict feed 每个操作 + 15%+ 15% per operation

哪些数据是通过客户管理的密钥加密的?What data gets encrypted with the customer-managed keys?

Azure Cosmos 帐户中存储的所有数据都将通过客户托管密钥加密,但以下元数据除外:All the data stored in your Azure Cosmos account is encrypted with the customer-managed keys, except for the following metadata:

现有的 Azure Cosmos 帐户是否支持客户管理的密钥?Are customer-managed keys supported for existing Azure Cosmos accounts?

此功能目前仅适用于新帐户。This feature is currently available only for new accounts.

是否有计划支持比帐户级别密钥更精细的粒度?Is there a plan to support finer granularity than account-level keys?

目前没有,但正在考虑容器级别的密钥。Not currently, but container-level keys are being considered.

如何判断是否在 Azure Cosmos 帐户上启用了客户管理的密钥?How can I tell if customer-managed keys are enabled on my Azure Cosmos account?

在 Azure 门户中,转到 Azure Cosmos 帐户,并在左侧菜单中查看“数据加密”项;如果此项存在,则在帐户中启用了客户管理的密钥:From the Azure portal, go to your Azure Cosmos account and watch for the Data Encryption entry in the left menu; if this entry exists, customer-managed keys are enabled on your account:

“数据加密”菜单项

还可以通过编程方式提取 Azure Cosmos 帐户的详细信息,并查找 keyVaultKeyUri 属性是否存在。You can also programmatically fetch the details of your Azure Cosmos account and look for the presence of the keyVaultKeyUri property. 请参阅上面的方法,在 PowerShell 中使用 Azure CLI. 实现此操作。See above for ways to do that in PowerShell and using the Azure CLI.

客户管理的密钥如何影响备份?How do customer-managed keys affect a backup?

Azure Cosmos DB 将定期自动备份存储在帐户中的数据。Azure Cosmos DB takes regular and automatic backups of the data stored in your account. 此操作可备份加密的数据。This operation backs up the encrypted data. 若要使用还原的备份,需要在备份时使用的加密密钥。To use the restored backup, the encryption key that you used at the time of the backup is required. 这意味着,没有执行任何吊销操作,并且备份时使用的密钥版本仍将保持启用状态。This means that no revocation was made and the version of the key that was used at the time of the backup will still be enabled.

如何吊销加密密钥?How do I revoke an encryption key?

密钥吊销是通过禁用密钥的最新版本来完成的:Key revocation is done by disabling the latest version of the key:

禁用密钥的版本

或者,若要从 Azure Key Vault 实例撤消所有密钥,可以删除授予 Azure Cosmos DB 主体的访问策略:Alternatively, to revoke all keys from an Azure Key Vault instance, you can delete the access policy granted to the Azure Cosmos DB principal:

删除 Azure Cosmos DB 主体的访问策略

吊销客户管理的密钥后可执行哪些操作?What operations are available after a customer-managed key is revoked?

吊销加密密钥后,删除帐户是唯一可执行的操作。The only operation possible when the encryption key has been revoked is account deletion.

后续步骤Next steps