Versionless keys (#36774)

Pietervanhove · VanMSFT · web-flow · commit 5e8b6b0d0032 · 2026-03-05T17:51:38.000-07:00
* Versionless keys

* Apply suggestions from code review

---------

Co-authored-by: Van To &lt;40007119+VanMSFT@users.noreply.github.com&gt;
diff --git a/azure-sql/database/transparent-data-encryption-byok-configure.md b/azure-sql/database/transparent-data-encryption-byok-configure.md
@@ -5,7 +5,7 @@ description: Learn how to configure an Azure SQL Database and Azure Synapse Anal
 author: Pietervanhove
 ms.author: pivanho
 ms.reviewer: vanto, mathoma
-ms.date: 06/25/2025
+ms.date: 03/05/2026
 ms.service: azure-sql
 ms.subservice: security
 ms.topic: how-to
@@ -43,7 +43,7 @@ This article applies to Azure SQL Database, Azure SQL Managed Instance, and Azur
   - The expiration date (if set) must be a future date and time
   - The key must be in the Enabled state
   - Able to perform *get*, *wrap key*, *unwrap key* operations
-- To use a Managed HSM key, follow instructions to [create and activate a Managed HSM using Azure CLI](/azure/key-vault/managed-hsm/quick-create-cli)
+- To use an Azure Managed HSM key, follow instructions to [create and activate a Managed HSM using Azure CLI](/azure/key-vault/managed-hsm/quick-create-cli)
 
 # [PowerShell](#tab/azure-powershell)
 
@@ -93,9 +93,22 @@ For adding permissions to your server on a Managed HSM, add the 'Managed HSM Cry
 > The combined length for the key vault name and key name cannot exceed 94 characters.
 
 > [!TIP]
-> An example KeyId from Azure Key Vault: `https://contosokeyvault.vault.azure.net/keys/Key1/<key-id>`
+> **Using versioned and versionless Azure Key Vault keys for TDE**
 >
-> An example KeyId from Managed HSM:<br/>https://contosoMHSM.managedhsm.azure.net/keys/myrsakey
+> When you set the TDE protector, you can reference an Azure Key Vault key using either a specific key version or a versionless key identifier.
+>
+> In both cases, Azure SQL Database always resolves and uses the latest enabled version of the key in Azure Key Vault or Azure Key Vault Managed HSM. Use versionless key identifiers to avoid embedding a specific key version in the TDE protector configuration.
+>
+> Versionless key identifiers are currently supported only for Azure SQL Database.
+>
+> Examples:
+> - Key identifier that includes a specific version
+> 
+>     `https://<key-vault-name>.vault.azure.net/keys/<key-name>/<key-version>`
+> 
+> - Versionless key identifier
+>
+>     `https://<key-vault-name>.vault.azure.net/keys/<key-name>`
 
 ```powershell
 # add the key from Azure Key Vault to the server
diff --git a/azure-sql/database/transparent-data-encryption-byok-create-server.md b/azure-sql/database/transparent-data-encryption-byok-create-server.md
@@ -5,7 +5,7 @@ description: Learn how to configure user-assigned managed identity and customer-
 author: Pietervanhove
 ms.author: pivanho
 ms.reviewer: vanto, mathoma
-ms.date: 01/23/2026
+ms.date: 03/05/2026
 ms.service: azure-sql-database
 ms.subservice: security
 ms.topic: how-to
@@ -85,6 +85,24 @@ This how-to guide outlines the steps to create an [Azure SQL Database logical se
 1. On the **Security** tab, under **Transparent Data Encryption Key Management**, you have the option to configure transparent data encryption for the server or database.
     - For **Server level key**: Select **Configure transparent data encryption**. Select **Customer-Managed Key**, and an option to select **Select a key** will appear. Select **Change key**. Select the desired **Subscription**, **Key vault**, **Key**, and **Version** for the customer-managed key to be used for TDE. Select the **Select** button.
 
+        > [!TIP]
+        > **Using versioned and versionless Azure Key Vault keys for TDE**
+        >
+        > When you set the TDE protector, you can reference an Azure Key Vault key using either a specific key version or a versionless key identifier.
+        >
+        > In both cases, Azure SQL Database always resolves and uses the latest enabled version of the key in Azure Key Vault or Azure Key Vault Managed HSM. Use versionless key identifiers to avoid embedding a specific key version in the TDE protector configuration.
+        >
+        > Versionless key identifiers are currently supported only for Azure SQL Database.
+        >
+        > Examples:
+        > - Key identifier that includes a specific version
+        > 
+        >     `https://<key-vault-name>.vault.azure.net/keys/<key-name>/<key-version>`
+        > 
+        > - Versionless key identifier
+        >
+        >     `https://<key-vault-name>.vault.azure.net/keys/<key-name>`
+    
     :::image type="content" source="media/transparent-data-encryption-byok-create-server/configure-tde-for-server.png" alt-text="Screenshot of configuring TDE for the server in Azure SQL.":::
 
     :::image type="content" source="media/transparent-data-encryption-byok-create-server/select-key-for-tde.png" alt-text="Screenshot selecting key for use with TDE.":::
@@ -105,7 +123,7 @@ This how-to guide outlines the steps to create an [Azure SQL Database logical se
 
 1. On the **Review + create** page, after reviewing, select **Create**.
 
-# [The Azure CLI](#tab/azure-cli)
+# [Azure CLI](#tab/azure-cli)
 
 For information on installing the current release of Azure CLI, see [Install the Azure CLI](/cli/azure/install-azure-cli) article.
 
diff --git a/azure-sql/database/transparent-data-encryption-byok-key-rotation.md b/azure-sql/database/transparent-data-encryption-byok-key-rotation.md
@@ -5,7 +5,7 @@ description: Learn how to rotate the Transparent data encryption (TDE) protector
 author: Pietervanhove
 ms.author: pivanho
 ms.reviewer: wiassaf, vanto, mathoma
-ms.date: 06/25/2025
+ms.date: 03/05/2026
 ms.service: azure-sql
 ms.subservice: security
 ms.topic: how-to
@@ -52,7 +52,7 @@ Go to the [Azure portal](https://portal.azure.com)
 
 For Az PowerShell module installation instructions, see [Install Azure PowerShell](/powershell/azure/install-az-ps). Use [the new Azure PowerShell Az module](/powershell/azure/new-azureps-module-az).
 
-# [The Azure CLI](#tab/azure-cli)
+# [Azure CLI](#tab/azure-cli)
 
 For installation, see [Install the Azure CLI](/cli/azure/install-azure-cli).
 
@@ -104,7 +104,7 @@ Set-AzSqlInstanceTransparentDataEncryptionProtector -Type AzureKeyVault -KeyId <
     -AutoRotationEnabled <boolean>
 ```
 
-# [The Azure CLI](#tab/azure-cli)
+# [Azure CLI](#tab/azure-cli)
 
 For information on installing the current release of Azure CLI, see [Install the Azure CLI](/cli/azure/install-azure-cli) article.
 
@@ -152,7 +152,7 @@ To enable automatic rotation for the TDE protector at the database level using P
 Set-AzSqlDatabase -ResourceGroupName <resource_group_name> -ServerName <server_name> -DatabaseName <database_name> -EncryptionProtectorAutoRotation:$true
 ```
 
-# [The Azure CLI](#tab/azure-cli)
+# [Azure CLI](#tab/azure-cli)
 
 To enable automatic rotation for the TDE protector at the database level using the Azure CLI, see the following command. Use the `--encryption-protector-auto-rotation` parameter and set to `True` to enable automatic key rotation or `False` to disable automatic key rotation.
 
@@ -234,7 +234,7 @@ The `<keyVaultKeyId>` can be [retrieved from Azure Key Vault](/azure/key-vault/k
 
 ### <a id="using-different-keys-for-each-server"></a> Use different keys for each server
 
-It's possible to configure the primary and secondary servers with a different key vault key when configuring TDE with CMK in the Azure portal. It's not evident in the Azure portal that the key used to protect the primary server is also the same key that protects the primary database that has been replicated to the secondary server. However, you can use PowerShell, the Azure CLI, or REST APIs to obtain details about keys that are used on the server. This shows that auto rotated keys are transferred from the primary server to the secondary server.
+It's possible to configure the primary and secondary servers with a different key vault key when configuring TDE with CMK in the Azure portal. It's not evident in the Azure portal that the key used to protect the primary server is also the same key that protects the primary database that has been replicated to the secondary server. However, you can use PowerShell, Azure CLI, or REST APIs to obtain details about keys that are used on the server. This shows that auto rotated keys are transferred from the primary server to the secondary server.
 
 Here's an example of using PowerShell commands to check for keys that are transferred from the primary server to the secondary server after key rotation.
 
@@ -325,7 +325,7 @@ Set-AzSqlInstanceTransparentDataEncryptionProtector -Type AzureKeyVault -KeyId <
    -InstanceName <ManagedInstanceName> -ResourceGroup <ManagedInstanceResourceGroupName>
 ```
 
-# [The Azure CLI](#tab/azure-cli)
+# [Azure CLI](#tab/azure-cli)
 
 Use the [az keyvault key create](/cli/azure/keyvault/key#az-keyvault-key-create) command to add a new key to the key vault.
 
@@ -407,7 +407,7 @@ Using the Azure portal to switch the TDE protector from Microsoft-managed to BYO
        -InstanceName <ManagedInstanceName> -ResourceGroup <ManagedInstanceResourceGroupName>e>
    ```
 
-# [The Azure CLI](#tab/azure-cli)
+# [Azure CLI](#tab/azure-cli)
 
 **Azure SQL Database**
 
diff --git a/azure-sql/database/transparent-data-encryption-byok-overview.md b/azure-sql/database/transparent-data-encryption-byok-overview.md
@@ -5,7 +5,7 @@ description: Bring Your Own Key (BYOK) support for transparent data encryption (
 author: Pietervanhove
 ms.author: pivanho
 ms.reviewer: wiassaf, vanto, mathoma, randolphwest
-ms.date: 09/16/2025
+ms.date: 03/05/2026
 ms.service: azure-sql
 ms.subservice: security
 ms.topic: concept-article
@@ -219,6 +219,24 @@ Auditors can use Azure Monitor to review managed HSM AuditEvent logs, if logging
 
 - To remove a potentially compromised key during a security incident without the risk of data loss, follow the steps in the article [Remove a Transparent Data Encryption (TDE) protector using PowerShell](transparent-data-encryption-byok-remove-tde-protector.md).
 
+> [!TIP]
+> **Using versioned and versionless Azure Key Vault keys for TDE**
+>
+> When you set the TDE protector, you can reference an Azure Key Vault key using either a specific key version or a versionless key identifier.
+>
+> In both cases, Azure SQL Database always resolves and uses the latest enabled version of the key in Azure Key Vault or Azure Key Vault Managed HSM. Use versionless key identifiers to avoid embedding a specific key version in the TDE protector configuration.
+>
+> Versionless key identifiers are currently supported only for Azure SQL Database.
+>
+> Examples:
+> - Key identifier that includes a specific version
+> 
+>     `https://<key-vault-name>.vault.azure.net/keys/<key-name>/<key-version>`
+> 
+> - Versionless key identifier
+>
+>     `https://<key-vault-name>.vault.azure.net/keys/<key-name>`
+
 ## Rotation of TDE protector
 
 Rotating the TDE protector for a server means to switch 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. The operation only decrypts and re-encrypts the database encryption key, not the entire database.
diff --git a/azure-sql/database/transparent-data-encryption-byok-remove-tde-protector.md b/azure-sql/database/transparent-data-encryption-byok-remove-tde-protector.md
@@ -1,11 +1,11 @@
 ---
-title: Remove TDE protector (PowerShell & the Azure CLI)
+title: Remove TDE protector (PowerShell & Azure CLI)
 titleSuffix: Azure SQL Database & Azure Synapse Analytics
 description: Learn how to respond to a potentially compromised TDE protector for Azure SQL Database or Azure Synapse Analytics using TDE with Bring Your Own Key (BYOK) support.
 author: Pietervanhove
 ms.author: pivanho
 ms.reviewer: wiassaf, vanto, mathoma
-ms.date: 06/25/2025
+ms.date: 03/05/2026
 ms.service: azure-sql-database
 ms.subservice: security
 ms.topic: how-to
@@ -43,9 +43,9 @@ This how-to guide goes over the approach to render databases **inaccessible** af
 
  For Az module installation instructions, see [Install Azure PowerShell](/powershell/azure/install-az-ps). Use [the new Azure PowerShell Az module](/powershell/azure/new-azureps-module-az).
 
-# [The Azure CLI](#tab/azure-cli)
+# [Azure CLI](#tab/azure-cli)
 
-For installation, see [Install the Azure CLI](/cli/azure/install-azure-cli).
+For installation, see [Install Azure CLI](/cli/azure/install-azure-cli).
 
 * * *
 
@@ -68,13 +68,13 @@ The following query returns the VLFs and the TDE Protector respective thumbprint
 SELECT * FROM sys.dm_db_log_info (database_id)
 ```
 
-Alternatively, you can use PowerShell or the Azure CLI:
+Alternatively, you can use PowerShell or Azure CLI:
 
 # [PowerShell](#tab/azure-powershell)
 
 The PowerShell command `Get-AzSqlServerKeyVaultKey` provides the thumbprint of the TDE Protector used in the query, so you can see which keys to keep and which keys to delete in Azure Key Vault. Only keys no longer used by the database can be safely deleted from Azure Key Vault.
 
-# [The Azure CLI](#tab/azure-cli)
+# [Azure CLI](#tab/azure-cli)
 
 The PowerShell command `az sql server key show` provides the thumbprint of the TDE Protector used in the query, so you can see which keys to keep and which keys to delete in Azure Key Vault. Only keys no longer used by the database can be safely deleted from Azure Key Vault.
 
@@ -125,9 +125,9 @@ The PowerShell command `az sql server key show` provides the thumbprint of the
    Restore-AzKeyVaultKey -VaultName <KeyVaultName> -InputFile <BackupFilePath>
    ```
 
-# [The Azure CLI](#tab/azure-cli)
+# [Azure CLI](#tab/azure-cli)
 
-For command reference, see the [Azure CLI keyvault](/cli/azure/keyvault/key).
+For command reference, see [Azure CLI keyvault](/cli/azure/keyvault/key).
 
 1. Create a [new key in Azure Key Vault](/cli/azure/keyvault/key#az-keyvault-key-create). Make sure this new key is created in a separate key vault from the potentially compromised TDE protector, since access control is provisioned on a vault level.
 
