PowerShell 和 Azure CLI：使用 Azure Key Vault 中由客户管理的密钥启用透明数据加密PowerShell and the Azure CLI: Enable Transparent Data Encryption with customer-managed key from Azure Key Vault

适用于： Azure SQL 数据库 Azure SQL 托管实例 Azure Synapse Analytics (SQL DW)

本文逐步介绍如何使用 Azure Key Vault 中的密钥对 Azure SQL 数据库或 Azure Synapse Analytics（以前成为 SQL Data Warehouse）启用透明数据加密 (TDE)。This article walks through how to use a key from Azure Key Vault for Transparent Data Encryption (TDE) on Azure SQL Database or Azure Synapse Analytics (formerly SQL Data Warehouse). 要了解更多关于 TDE 与 Azure Key Vault 集成（即自带密钥 (BYOK) 支持）的信息，请访问使用 Azure Key Vault 中由客户管理的密钥进行 TDE。To learn more about the TDE with Azure Key Vault integration - Bring Your Own Key (BYOK) Support, visit TDE with customer-managed keys in Azure Key Vault.

PowerShell 先决条件Prerequisites for PowerShell

  • 必须有一个 Azure 订阅，并且是该订阅的管理员。You must have an Azure subscription and be an administrator on that subscription.
  • 必须安装并运行 Azure PowerShell。You must have Azure PowerShell installed and running.
  • 创建用于 TDE 的 Azure Key Vault 和密钥。Create an Azure Key Vault and Key to use for TDE.
  • 密钥必须包含用于 TDE 的以下特性：The key must have the following attributes to be used for TDE:
    • 无过期日期No expiration date
    • 未禁用Not disabled
    • 能够执行“获取”、“包装密钥”和“解包密钥”操作 Able to perform get, wrap key, unwrap key operations

有关 Az 模块安装说明，请参阅安装 Azure PowerShell。For Az module installation instructions, see Install Azure PowerShell. 若要了解具体的 cmdlet，请参阅 AzureRM.Sql。For specific cmdlets, see AzureRM.Sql.

有关 Key Vault 的具体信息，请参阅 Key Vault 的 PowerShell 说明和如何将 Key Vault 软删除与 PowerShell 配合使用。For specifics on Key Vault, see PowerShell instructions from Key Vault and How to use Key Vault soft-delete with PowerShell.

重要

仍然支持 PowerShell Azure 资源管理器 (RM) 模块，但是所有未来的开发都是针对 Az.Sql 模块。The PowerShell Azure Resource Manager (RM) module is still supported, but all future development is for the Az.Sql module. AzureRM 模块至少在 2020 年 12 月之前将继续接收 bug 修补程序。The AzureRM module will continue to receive bug fixes until at least December 2020. Az 模块和 AzureRm 模块中的命令参数大体上是相同的。The arguments for the commands in the Az module and in the AzureRm modules are substantially identical. 若要详细了解其兼容性，请参阅新 Azure PowerShell Az 模块简介。For more about their compatibility, see Introducing the new Azure PowerShell Az module.

将 Azure Active Directory (Azure AD) 标识分配给服务器Assign an Azure Active Directory (Azure AD) identity to your server

如果你已有服务器，请使用以下命令将 Azure Active Directory (Azure AD) 标识添加到该服务器：If you have an existing server, use the following to add an Azure Active Directory (Azure AD) identity to your server:

$server = Set-AzSqlServer -ResourceGroupName <SQLDatabaseResourceGroupName> -ServerName <LogicalServerName> -AssignIdentity

如果正在创建服务器，请在创建服务器期间，结合 -Identity 标记使用 New-AzSqlServer cmdlet 来添加 Azure AD 标识：If you are creating a server, use the New-AzSqlServer cmdlet with the tag -Identity to add an Azure AD identity during server creation:

$server = New-AzSqlServer -ResourceGroupName <SQLDatabaseResourceGroupName> -Location <RegionName> `
    -ServerName <LogicalServerName> -ServerVersion "12.0" -SqlAdministratorCredentials <PSCredential> -AssignIdentity

向服务器授予 Key Vault 权限Grant Key Vault permissions to your server

将 Key Vault 中的密钥用于 TDE 之前，请使用 Set-AzKeyVaultAccessPolicy cmdlet 向服务器授权 Key Vault 的访问权限。Use the Set-AzKeyVaultAccessPolicy cmdlet to grant your server access to the key vault before using a key from it for TDE.

Set-AzKeyVaultAccessPolicy -VaultName <KeyVaultName> `
    -ObjectId $server.Identity.PrincipalId -PermissionsToKeys get, wrapKey, unwrapKey

将 Key Vault 密钥添加到服务器并设置 TDE 保护器Add the Key Vault key to the server and set the TDE Protector

备注

Key Vault 名称和密钥名称的总长度不能超过 94 个字符。The combined length for the key vault name and key name cannot exceed 94 characters.

提示

Key Vault 中的示例 KeyId： https://contosokeyvault.vault.azure.cn/keys/Key1/1a1a2b2b3c3c4d4d5e5e6f6f7g7g8h8hAn example KeyId from Key Vault: https://contosokeyvault.vault.azure.cn/keys/Key1/1a1a2b2b3c3c4d4d5e5e6f6f7g7g8h8h

# add the key from Key Vault to the server
Add-AzSqlServerKeyVaultKey -ResourceGroupName <SQLDatabaseResourceGroupName> -ServerName <LogicalServerName> -KeyId <KeyVaultKeyId>

# set the key as the TDE protector for all resources under the server
Set-AzSqlServerTransparentDataEncryptionProtector -ResourceGroupName <SQLDatabaseResourceGroupName> -ServerName <LogicalServerName> `
   -Type AzureKeyVault -KeyId <KeyVaultKeyId>

# confirm the TDE protector was configured as intended
Get-AzSqlServerTransparentDataEncryptionProtector -ResourceGroupName <SQLDatabaseResourceGroupName> -ServerName <LogicalServerName>

启用 TDETurn on TDE

使用 Set-AzSqlDatabaseTransparentDataEncryption cmdlet 来启用 TDE。Use the Set-AzSqlDatabaseTransparentDataEncryption cmdlet to turn on TDE.

Set-AzSqlDatabaseTransparentDataEncryption -ResourceGroupName <SQLDatabaseResourceGroupName> `
   -ServerName <LogicalServerName> -DatabaseName <DatabaseName> -State "Enabled"

现已使用 Key Vault 中的加密密钥为数据库或数据仓库启用了 TDE。Now the database or data warehouse has TDE enabled with an encryption key in Key Vault.

检查加密状态和加密活动Check the encryption state and encryption activity

使用 Get-AzSqlDatabaseTransparentDataEncryption 获取加密状态，使用 Get- AzSqlDatabaseTransparentDataEncryptionActivity 检查数据库或数据仓库的加密进度。Use the Get-AzSqlDatabaseTransparentDataEncryption to get the encryption state and the Get-AzSqlDatabaseTransparentDataEncryptionActivity to check the encryption progress for a database or data warehouse.

# get the encryption state
Get-AzSqlDatabaseTransparentDataEncryption -ResourceGroupName <SQLDatabaseResourceGroupName> `
   -ServerName <LogicalServerName> -DatabaseName <DatabaseName> `

# check the encryption progress for a database or data warehouse
Get-AzSqlDatabaseTransparentDataEncryptionActivity -ResourceGroupName <SQLDatabaseResourceGroupName> `
   -ServerName <LogicalServerName> -DatabaseName <DatabaseName>

有用的 PowerShell cmdletUseful PowerShell cmdlets

  • 使用 Set-AzSqlDatabaseTransparentDataEncryption cmdlet 来禁用 TDE。Use the Set-AzSqlDatabaseTransparentDataEncryption cmdlet to turn off TDE.

    Set-AzSqlDatabaseTransparentDataEncryption -ServerName <LogicalServerName> -ResourceGroupName <SQLDatabaseResourceGroupName> `
    -DatabaseName <DatabaseName> -State "Disabled"

  • 使用 Get-AzSqlServerKeyVaultKey cmdlet 可返回已添加到服务器的 Key Vault 密钥列表。Use the Get-AzSqlServerKeyVaultKey cmdlet to return the list of Key Vault keys added to the server.

    # KeyId is an optional parameter, to return a specific key version
Get-AzSqlServerKeyVaultKey -ServerName <LogicalServerName> -ResourceGroupName <SQLDatabaseResourceGroupName>

  • 使用 Remove-AzSqlServerKeyVaultKey 可从服务器中删除 Key Vault 密钥。Use the Remove-AzSqlServerKeyVaultKey to remove a Key Vault key from the server.

    # the key set as the TDE Protector cannot be removed
Remove-AzSqlServerKeyVaultKey -KeyId <KeyVaultKeyId> -ServerName <LogicalServerName> -ResourceGroupName <SQLDatabaseResourceGroupName>

故障排除Troubleshooting

如果出现问题，请查看以下内容：Check the following if an issue occurs:

  • 如果找不到 Key Vault，请确保在正确的订阅中操作。If the key vault cannot be found, make sure you're in the right subscription.

    Get-AzSubscription -SubscriptionId <SubscriptionId>
  • 如果无法将新密钥添加到服务器，或无法将新密钥更新为 TDE 保护器，请检查以下项：If the new key cannot be added to the server, or the new key cannot be updated as the TDE Protector, check the following:
    • 密钥不应有过期日期The key should not have an expiration date
    • 密钥必须支持“获取”、“包装密钥”和“解包密钥”操作。 The key must have the get, wrap key, and unwrap key operations enabled.

后续步骤Next steps