Skip to content

Update contributor docs for Bitlocker #43241

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
getvictor merged 1 commit into from
Apr 13, 2026
+21 −8
Merged

Update contributor docs for Bitlocker #43241

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 19 additions & 6 deletions docs/Contributing/architecture/mdm/disk-encryption.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/Contributing/product-groups/mdm/mdm-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading