Rotate the Transparent Data Encryption (TDE) protector using PowerShell

This article describes key rotation for an Azure SQL server using a TDE protector from Azure Key Vault. Rotating an Azure SQL server’s TDE protector means switching to a new asymmetric key that protects the databases on the server. Key rotation is an online operation and should only take a few seconds to complete, because this only decrypts and re-encrypts the database’s data encryption key, not the entire database.

This guide discusses two options to rotate the TDE protector on the server.

Note

A paused SQL Data Warehouse must be resumed before key rotations.

Important

Do Not Delete previous versions of the key after a rollover. When keys are rolled over, some data is still encrypted with the previous keys, such as older database backups.

Prerequisites

Note

This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.

Important

The PowerShell Azure Resource Manager module is still supported by Azure SQL Database, but all future development is for the Az.Sql module. For these cmdlets, see AzureRM.Sql. The arguments for the commands in the Az module and in the AzureRm modules are substantially identical.

Manual key rotation

Manual key rotation uses the Add-AzKeyVaultKey, Add-AzSqlServerKeyVaultKey, and Set-AzSqlServerTransparentDataEncryptionProtector cmdlets to add a completely new key, which could be under a new key name or even another key vault. Using this approach supports adding the same key to different key vaults to support high-availability and geo-dr scenarios.

Note

The combined length for the key vault name and key name cannot exceed 94 characters.

# Add a new key to Key Vault
Add-AzKeyVaultKey `
-VaultName <KeyVaultName> `
-Name <KeyVaultKeyName> `
-Destination <HardwareOrSoftware>

# Add the new key from Key Vault to the server
Add-AzSqlServerKeyVaultKey `
-KeyId <KeyVaultKeyId> `
-ServerName <LogicalServerName> `
-ResourceGroup <SQLDatabaseResourceGroupName>

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

Option 2: Manual rotation

The option uses the Add-AzKeyVaultKey, Add-AzSqlServerKeyVaultKey, and Set-AzSqlServerTransparentDataEncryptionProtector cmdlets to add a completely new key, which could be under a new key name or even another key vault.

Note

The combined length for the key vault name and key name cannot exceed 94 characters.

# Add a new key to Key Vault
Add-AzKeyVaultKey `
-VaultName <KeyVaultName> `
-Name <KeyVaultKeyName> `
-Destination <HardwareOrSoftware>

# Add the new key from Key Vault to the server
Add-AzSqlServerKeyVaultKey `
-KeyId <KeyVaultKeyId> `
-ServerName <LogicalServerName> `
-ResourceGroup <SQLDatabaseResourceGroupName>   

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

Other useful PowerShell cmdlets

  • To switch the TDE protector from Microsoft-managed to BYOK mode, use the Set-AzSqlServerTransparentDataEncryptionProtector cmdlet.

    Set-AzSqlServerTransparentDataEncryptionProtector `
    -Type AzureKeyVault `
    -KeyId <KeyVaultKeyId> `
    -ServerName <LogicalServerName> `
    -ResourceGroup <SQLDatabaseResourceGroupName>
    
  • To switch the TDE protector from BYOK mode to Microsoft-managed, use the Set-AzSqlServerTransparentDataEncryptionProtector cmdlet.

    Set-AzSqlServerTransparentDataEncryptionProtector `
    -Type ServiceManaged `
    -ServerName <LogicalServerName> `
    -ResourceGroup <SQLDatabaseResourceGroupName> 
    

Next steps