From dbe6e4ee2d2860ace8fe13d6f0a0b3b2cdfd7676 Mon Sep 17 00:00:00 2001
From: Tom Proctor <tomhjp@users.noreply.github.com>
Date: Wed, 3 Apr 2024 11:35:31 +0100
Subject: [PATCH] Docs: Fix SQL Server EKM Provider KEK rotation instructions
 (#25255)

---
 .../docs/platform/mssql/installation.mdx      | 37 +----------
 .../content/docs/platform/mssql/rotation.mdx  | 62 +++++++++++++++++++
 website/data/docs-nav-data.json               |  4 ++
 3 files changed, 68 insertions(+), 35 deletions(-)
 create mode 100644 website/content/docs/platform/mssql/rotation.mdx

diff --git a/website/content/docs/platform/mssql/installation.mdx b/website/content/docs/platform/mssql/installation.mdx
index b19e9e51c2..b743c0f665 100644
--- a/website/content/docs/platform/mssql/installation.mdx
+++ b/website/content/docs/platform/mssql/installation.mdx
@@ -221,38 +221,5 @@ installation.
 
 ## Key rotation
 
-Both the database encryption key and Vault Transit's asymmetric key can be rotated independently.
-
-To rotate the database encryption key, you can execute the
-[following SQL query](https://docs.microsoft.com/en-us/sql/t-sql/statements/alter-database-encryption-key-transact-sql?view=azuresqldb-current)
-in Microsoft SQL Server Management Studio:
-
-```sql
-USE TestTDE;
-GO
-
-ALTER DATABASE ENCRYPTION KEY
-REGENERATE WITH ALGORITHM = AES_256;
-GO
-
-SELECT * FROM sys.dm_database_encryption_keys;
-```
-
-To rotate the asymmetric key in Vault's Transit, you can use the standard
-[`/rotate`](/vault/api-docs/secret/transit#rotate-key) endpoint:
-
-```shell-session
-$ vault write -f transit/keys/ekm-encryption-key/rotate
-```
-
-After rotating the Vault asymmetric key, you can force SQL Server to re-encrypt the database encryption
-key with the newest version of the Vault key with:
-
-```sql
-USE TestTDE;
-GO
-
-ALTER DATABASE ENCRYPTION KEY
-ENCRYPTION BY SERVER ASYMMETRIC KEY TransitVaultAsymmetric;
-GO
-```
+See [key rotation](/vault/docs/platform/mssql/rotation) for guidance on rotating
+the encryption keys.
diff --git a/website/content/docs/platform/mssql/rotation.mdx b/website/content/docs/platform/mssql/rotation.mdx
new file mode 100644
index 0000000000..5d290d6edf
--- /dev/null
+++ b/website/content/docs/platform/mssql/rotation.mdx
@@ -0,0 +1,62 @@
+---
+layout: docs
+page_title: Rotating encryption keys with the Vault EKM Provider
+description: Steps to rotate the symmetric Database Encryption Key (DEK) and the asymmetric Key Encryption Key (KEK) when using the Vault EKM Provider for Microsoft SQL Server.
+---
+
+# Key rotation
+
+Both the database encryption key and Vault Transit's asymmetric key can be rotated independently.
+
+## Database encryption key (DEK) rotation
+
+To rotate the database encryption key, you can execute the
+[following SQL query](https://docs.microsoft.com/en-us/sql/t-sql/statements/alter-database-encryption-key-transact-sql?view=azuresqldb-current)
+in Microsoft SQL Server Management Studio:
+
+```sql
+USE TestTDE;
+GO
+
+ALTER DATABASE ENCRYPTION KEY
+REGENERATE WITH ALGORITHM = AES_256;
+GO
+
+SELECT * FROM sys.dm_database_encryption_keys;
+```
+
+## Key encryption key (KEK) rotation
+
+To rotate the asymmetric key in Vault's Transit, you can use the standard
+[`/rotate`](/vault/api-docs/secret/transit#rotate-key) endpoint:
+
+```shell-session
+$ vault write -f transit/keys/ekm-encryption-key/rotate
+```
+
+After rotating the Vault asymmetric key, you can force SQL Server to re-encrypt the database encryption
+key with the newest version of the Vault key by creating a new asymmetric key:
+
+```sql
+use master;
+GO
+
+CREATE ASYMMETRIC KEY TransitVaultAsymmetricV2
+FROM PROVIDER TransitVaultProvider
+WITH CREATION_DISPOSITION = OPEN_EXISTING,
+PROVIDER_KEY_NAME = 'ekm-encryption-key';
+
+
+CREATE CREDENTIAL TransitVaultTDECredentialsV2
+    WITH IDENTITY = '<approle-role-id>',
+    SECRET = '<approle-secret-id>'
+FOR CRYPTOGRAPHIC PROVIDER TransitVaultProvider;
+GO
+
+CREATE LOGIN TransitVaultTDELoginV2 FROM ASYMMETRIC KEY TransitVaultAsymmetricV2;
+
+use TestTDE;
+go
+
+ALTER DATABASE ENCRYPTION KEY ENCRYPTION BY SERVER ASYMMETRIC KEY TransitVaultAsymmetricV2;
+```
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index ae22d69b40..3367d7d88f 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -2221,6 +2221,10 @@
             "title": "Configuration",
             "path": "platform/mssql/configuration"
           },
+          {
+            "title": "Key Rotation",
+            "path": "platform/mssql/rotation"
+          },
           {
             "title": "Upgrading",
             "path": "platform/mssql/upgrading"