diff --git a/docs/Contributing/windows-mdm-glossary-and-protocol.md b/docs/Contributing/windows-mdm-glossary-and-protocol.md new file mode 100644 index 000000000..2f09f786b --- /dev/null +++ b/docs/Contributing/windows-mdm-glossary-and-protocol.md @@ -0,0 +1,58 @@ +# Protocol + +This sequence diagram outlines the manual MDM enrollment process. + +```mermaid +sequenceDiagram + participant windows as Windows + participant orbit as Orbit + participant server as fleet server + + orbit->>+server: POST /api/fleet/orbit/enroll
enroll_secret, hardware_uuid, etc. + server-->>-orbit: orbit_node_key + + loop every 30 seconds + orbit->>+server: POST /api/fleet/orbit/config
orbit_node_key + server-->>-orbit: pending notifications + end + + note over orbit: Receive enrollment notification
needs_programmatic_windows_mdm_enrollment
windows_mdm_discovery_endpoint + orbit->>windows: mdmregistration.dll
RegisterDeviceWithManagement
discovery endpoint, node key + + windows->>+server: POST /api/mdm/microsoft/discovery + server-->>-windows: EnrollmentServiceURL, EnrollmentPolicyServiceUrl + + windows->>+server: POST /api/mdm/microsoft/policy
DeviceEnrollmentUserToken (node key) + server-->>-windows: Policy Schema, Certificate requirements + activate windows + note left of windows: Generate keypair + deactivate windows + windows->>+server: POST /api/mdm/microsoft/enroll
Self-signed CSR & cert values, DeviceID
DeviceEnrollmentUserToken (node key) + note right of server: Creates certificate signed by WSTEP ident key + server-->>-windows: Signed certificate, management endpoint, enrollment parameters + + loop SYNCML MDM Protocol (mTLS) + windows->>+server: POST /api/mdm/microsoft/management
DeviceID + server-->>-windows: Response + end +``` + +# Glossary + +## WSTEP + +[WSTEP](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-wstep/ac55b8cc-9ade-4982-b135-991d574ade74) is the protocol Microsoft uses to automate certificate requesting and singing. It is similar to the SCEP process used by macOS. + +The certificate created through the WSTEP process is used to authenticate mTLS between the host and management endpoint. + +## SyncML + +[SyncML](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-wstep/ac55b8cc-9ade-4982-b135-991d574ade74) is an XML dialect used by Microsoft for Device Management. + +## mTLS + +[Mutual Transport Layer Security](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/) is a method for securing communications between two parties, in which both parties present signed certificates. This is different from standard TLS, where only the most provides a certificate. This allows both parties to authenticate the other's identity. + +## MDM Protocol Summary + +https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-mdm/33769a92-ac31-47ef-ae7b-dc8501f7104f