From adfe6b59bb9573a01ed8b6cede80ff7fedb4ee03 Mon Sep 17 00:00:00 2001
From: Victor Lyuboslavsky <2685025+getvictor@users.noreply.github.com>
Date: Mon, 13 Apr 2026 09:02:43 -0500
Subject: [PATCH] Update contributor docs for Bitlocker (#43241)

<!-- Add the related story/sub-task/bug number, like Resolves #123, or
remove if NA -->
**Related issue:** Resolves #40809
---
 .../architecture/mdm/disk-encryption.md       | 25 ++++++++++++++-----
 .../product-groups/mdm/mdm-overview.md        |  4 +--
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/docs/Contributing/architecture/mdm/disk-encryption.md b/docs/Contributing/architecture/mdm/disk-encryption.md
index 45b4c70923..7e5bc64f56 100644
--- a/docs/Contributing/architecture/mdm/disk-encryption.md
+++ b/docs/Contributing/architecture/mdm/disk-encryption.md
@@ -118,10 +118,18 @@ When disk encryption is enabled, the server sends a notification to orbit, which
 [Win32_EncryptableVolume class](https://learn.microsoft.com/en-us/windows/win32/secprov/getencryptionmethod-win32-encryptablevolume)
 to encrypt the used space of the disk with TPM and Numerical Password protectors and generate an encryption key.
 
-If the disk is already encrypted, it will first be decrypted and then re-encrypted.
+If the disk is already encrypted, orbit rotates the recovery key: it adds a new Fleet-managed
+Numerical Password protector, removes old recovery key protectors, and escrows the new key. The disk
+is never decrypted. This matches how other MDM platforms handle pre-encrypted disks and avoids issues
+with secondary drives that use BitLocker auto-unlock (which prevents decrypting the OS drive).
 
-After the disk is encrypted, orbit sends the key back to the server using an orbit-authenticated
-endpoint (`POST /api/fleet/orbit/disk_encryption_key`).
+After the disk is encrypted (or the key is rotated), orbit sends the key back to the server using an
+orbit-authenticated endpoint (`POST /api/fleet/orbit/disk_encryption_key`).
+
+The server determines whether the disk is encrypted by checking both `conversion_status` (whether
+the data is encrypted) and `protection_status` (whether the TPM protector is active) from the
+osquery `bitlocker_info` table. If the disk is encrypted but protection is off (e.g., BitLocker
+suspended for a BIOS update), the host shows "Action required" in the Fleet UI.
 
 ```mermaid
 sequenceDiagram
@@ -135,14 +143,19 @@ sequenceDiagram
         host->>fleet: Enroll in Fleet MDM
         fleet->>host: Orbit/osquery installed
         fleetd->>fleet: request vitals queries
-        fleet->>fleetd: Return reports including encryption status
+        fleet->>fleetd: Return reports including encryption status<br>(protection_status and conversion_status)
         fleetd->>fleet: return report data including encryption status
         fleet->>fleetd: Enable notifs.EnforceBitLockerEncryption in orbit<br>config because Host is encrypted but no<br>key is escrowed or host is not encrypted
-        fleetd->>host: Decrypt OS volume(if encrypted)
-        fleetd->>fleetd: Wait for decryption
+        alt Disk not encrypted
         fleetd->>host: Create TPM and Numerical Password protectors
         host->>fleetd: Return recovery key after creating protectors
         fleetd->>host: Encrypt OS volume
+        else Disk already encrypted
+        fleetd->>host: Add new Numerical Password protector
+        host->>fleetd: Return new recovery key
+        fleetd->>host: Remove old recovery key protectors
+        fleetd->>host: Ensure TPM protector exists
+        end
         fleetd->>fleet: Send recovery key
         fleetd->>fleet: request vitals reports
         fleet->>fleetd: Return vitals reports including query<br>to check encryption status
diff --git a/docs/Contributing/product-groups/mdm/mdm-overview.md b/docs/Contributing/product-groups/mdm/mdm-overview.md
index f5451012c0..1542e89cfc 100644
--- a/docs/Contributing/product-groups/mdm/mdm-overview.md
+++ b/docs/Contributing/product-groups/mdm/mdm-overview.md
@@ -160,9 +160,9 @@ If we're not able to decrypt the key for a host, the key needs to be rotated. Ro
 
 Disk encryption in Windows is performed entirely by orbit.
 
-When disk encryption is enabled, the server sends a notification to orbit, who calls the [Win32_EncryptableVolume class](https://learn.microsoft.com/en-us/windows/win32/secprov/getencryptionmethod-win32-encryptablevolume) to encrypt/decrypt the disk and generate an encryption key.
+When disk encryption is enabled, the server sends a notification to orbit, which calls the [Win32_EncryptableVolume class](https://learn.microsoft.com/en-us/windows/win32/secprov/getencryptionmethod-win32-encryptablevolume) to encrypt the disk and generate an encryption key. If the disk is already encrypted, orbit rotates the recovery key (adds a new Fleet-managed protector, removes old ones) without decrypting.
 
-After the disk is encrypted, orbit sends the key back to the server using an orbit-authenticated endpoint (`POST /api/fleet/orbit/disk_encryption_key`)
+After the disk is encrypted (or the key is rotated), orbit sends the key back to the server using an orbit-authenticated endpoint (`POST /api/fleet/orbit/disk_encryption_key`)
 
 ### Load testing