From d7c0576562b7a14800b41fcc2dfcc0fea3ed9561 Mon Sep 17 00:00:00 2001 From: Vinay Pamnani <37223378+vinaypamnani-msft@users.noreply.github.com> Date: Mon, 27 Feb 2023 17:29:47 -0500 Subject: [PATCH] HealthAttestation CSP --- .../enterprisedesktopappmanagement2-xsd.md | 105 - .../mdm/healthattestation-csp.md | 2174 ++++++++++------- .../mdm/healthattestation-ddf.md | 862 ++++--- windows/client-management/mdm/toc.yml | 2 +- 4 files changed, 1644 insertions(+), 1499 deletions(-) delete mode 100644 windows/client-management/mdm/enterprisedesktopappmanagement2-xsd.md diff --git a/windows/client-management/mdm/enterprisedesktopappmanagement2-xsd.md b/windows/client-management/mdm/enterprisedesktopappmanagement2-xsd.md deleted file mode 100644 index 7bdeb81114..0000000000 --- a/windows/client-management/mdm/enterprisedesktopappmanagement2-xsd.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: EnterpriseDesktopAppManagement XSD -description: This topic contains the XSD schema file for the EnterpriseDesktopAppManagement configuration service provider’s DownloadInstall parameter. -ms.reviewer: -manager: aaroncz -ms.author: vinpa -ms.topic: article -ms.prod: windows-client -ms.technology: itpro-manage -author: vinaypamnani-msft -ms.date: 06/26/2017 ---- - -# EnterpriseDesktopAppManagement XSD - -This topic contains the XSD schema file for the EnterpriseDesktopAppManagement configuration service provider’s DownloadInstall parameter. - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -The following table describes the various elements and attributes of the XSD file: - -  - -| Name | Description | -|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| MsiInstallJob | Root element | -| id | The application identifier for the application being installed. | -| Product | Child element of MsiInstallJob | -| Version | String representation of the application version | -| Download | Child element of Product. Container for download configuration information. | -| ContentURLList | Child element of Download. Contains list of one or more content download URL locators in the form of ContentURL elements. | -| ContentURL | Location that content should be downloaded from. Must be a property formatted URL that points to the MSI file. | -| Validation | Contains information used to validate content authenticity. | -| FileHash | SHA256 hash value of file content. | -| Enforcement | Installation properties to be used when installing this MSI | -| CommandLine | Command-line options to be used when calling MSIEXEC.exe | -| Timeout | Amount of time in minutes that the installation process can run before the installer considers the installation may have failed and no longer monitors the installation operation. | -| RetryCount | Number of times the download and installation operation will be retried before the installation will be marked as failed. | -| RetryInterval | Amount of time in minutes between retry operations. | - -  - -  - -  - - - - - - diff --git a/windows/client-management/mdm/healthattestation-csp.md b/windows/client-management/mdm/healthattestation-csp.md index 63c5843f83..33cb45bf8d 100644 --- a/windows/client-management/mdm/healthattestation-csp.md +++ b/windows/client-management/mdm/healthattestation-csp.md @@ -1,29 +1,23 @@ --- -title: Device HealthAttestation CSP -description: Learn how the DHA-CSP enables enterprise IT managers to assess if a device is booted to a trusted and compliant state, and take enterprise policy actions. -ms.reviewer: +title: HealthAttestation CSP +description: Learn more about the HealthAttestation CSP. +author: vinaypamnani-msft manager: aaroncz ms.author: vinpa -ms.topic: article +ms.date: 02/27/2023 +ms.localizationpriority: medium ms.prod: windows-client ms.technology: itpro-manage -author: vinaypamnani-msft -ms.date: 4/5/2022 +ms.topic: reference --- -# Device HealthAttestation CSP + -The table below shows the applicability of Windows: - -|Edition|Windows 10|Windows 11| -|--- |--- |--- | -|Home|Yes|Yes| -|Pro|Yes|Yes| -|Windows SE|No|Yes| -|Business|Yes|Yes| -|Enterprise|Yes|Yes| -|Education|Yes|Yes| + +# HealthAttestation CSP + + The Device HealthAttestation configuration service provider (DHA-CSP) enables enterprise IT administrators to assess if a device is booted to a trusted and compliant state, and to take enterprise policy actions. The following list is a description of the functions performed by the Device HealthAttestation CSP: @@ -32,32 +26,782 @@ The following list is a description of the functions performed by the Device Hea - Forwards DHA-BootData to a Device Health Attestation Service (DHA-Service) - Receives an encrypted blob (DHA-EncBlob) from DHA-Service, and stores it in a local cache on the device - Receives attestation requests (DHA-Requests) from a DHA-Enabled MDM, and replies with Device Health Attestation data (DHA-Data) + + +The following list shows the HealthAttestation configuration service provider nodes: + +- ./Vendor/MSFT/HealthAttestation + - [AttestStatus](#atteststatus) + - [Certificate](#certificate) + - [CorrelationID](#correlationid) + - [CurrentProtocolVersion](#currentprotocolversion) + - [ForceRetrieve](#forceretrieve) + - [GetAttestReport](#getattestreport) + - [GetServiceCorrelationIDs](#getservicecorrelationids) + - [HASEndpoint](#hasendpoint) + - [MaxSupportedProtocolVersion](#maxsupportedprotocolversion) + - [Nonce](#nonce) + - [PreferredMaxProtocolVersion](#preferredmaxprotocolversion) + - [Status](#status) + - [TpmReadyStatus](#tpmreadystatus) + - [TriggerAttestation](#triggerattestation) + - [VerifyHealth](#verifyhealth) + + + +## AttestStatus + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 11, version 21H2 [10.0.22000] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/AttestStatus +``` + + + + +AttestStatus maintains the success or failure status code for the last attestation session. + + + + +The status is always cleared prior to making the attest service call. + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | int | +| Access Type | Get | + + + + +**Example**: + +- Templated SyncML Call: + + ```xml + + + + + + + ./Device/Vendor/MSFT/HealthAttestation/AttestStatus + + + + + + + + ``` + +- Sample Response: + + ```console + If Successful: 0 + If Failed: A corresponding HRESULT error code. Example: 0x80072efd, WININET_E_CANNOT_CONNECT + ``` + + + + + +## Certificate + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 10, version 1511 [10.0.10586] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/Certificate +``` + + + + +Instructs the DHA-CSP to forward DHA-Data to the MDM server. + + + + +Value type is a base64 string. + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | chr (string) | +| Access Type | Get | + + + + + + + + + +## CorrelationID + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 10, version 1511 [10.0.10586] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/CorrelationID +``` + + + + +Identifies a unique device health attestation session. CorrelationId is used to correlate DHA-Service logs with the MDM server events and Client event logs for debug and troubleshooting. + + + + + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | chr (string) | +| Access Type | Get | + + + + + + + + + +## CurrentProtocolVersion + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 10, version 1709 [10.0.16299] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/CurrentProtocolVersion +``` + + + + +Provides the current protocol version that the client is using to communicate with the Health Attestation Service. + + + + + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | int | +| Access Type | Get | + + + + + + + + + +## ForceRetrieve + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 10, version 1511 [10.0.10586] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/ForceRetrieve +``` + + + + +Instructs the client to initiate a new request to DHA-Service, and get a new DHA-EncBlob (a summary of the boot state that is issued by DHA-Service). This option should only be used if the MDM server enforces a certificate freshness policy, which needs to force a device to get a fresh encrypted blob from DHA-Service. + + + + + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | bool | +| Access Type | Get, Replace | +| Default Value | False | + + + +**Allowed values**: + +| Value | Description | +|:--|:--| +| false (Default) | False. | +| true | True. | + + + + + + + + + +## GetAttestReport + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 11, version 21H2 [10.0.22000] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/GetAttestReport +``` + + + + +Retrieve attestation session report if exists. + + + + +The report is stored in a registry key in the respective MDM enrollment store. + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | chr (string) | +| Access Type | Get | + + + + +**Example**: + +- Templated SyncML Call: + + ```xml + + + + + + + ./Device/Vendor/MSFT/HealthAttestation/GetAttestReport + + + + + + + + ``` + +- Sample data: + + ```console + If Success: JWT token: aaaaaaaaaaaaa.bbbbbbbbbbbbb.cccccccccc + If failed: Previously cached report if available (the token may have already expired per the attestation policy). + OR Sync ML 404 error if no cached report available. + ``` + + + + + +## GetServiceCorrelationIDs + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 11, version 21H2 [10.0.22000] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/GetServiceCorrelationIDs +``` + + + + +Retrieve service correlation IDs if exist. + + + + +If there's more than one correlation ID, they're separated by ";" in the string. + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | chr (string) | +| Access Type | Get | + + + + +**Example**: + +- Templated SyncML Call: + + ```xml + + + + + + + ./Device/Vendor/MSFT/HealthAttestation/GetServiceCorrelationIDs + + + + + + + + ``` + +- Sample data: + + ```console + If success: GUID returned by the attestation service: 1k9+vQOn00S8ZK33;CMc969r1JEuHwDpM + If Trigger Attestation call failed and no previous data is present: The field remains empty. + Otherwise, the last service correlation id will be returned. + In a successful attestation there are two calls between client and MAA and for each call the GUID is separated by semicolon. + ``` + + + + + +## HASEndpoint + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 10, version 1511 [10.0.10586] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/HASEndpoint +``` + + + + +Identifies the fully qualified domain name (FQDN) of the DHA-Service that is assigned to perform attestation. If an FQDN is not assigned, DHA-Cloud (Microsoft owned and operated cloud service) will be used as the default attestation service. + + + + + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | chr (string) | +| Access Type | Get, Replace | +| Default Value | has.spserv.microsoft.com. | + + + + + + + + + +## MaxSupportedProtocolVersion + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 10, version 1709 [10.0.16299] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/MaxSupportedProtocolVersion +``` + + + + +Returns the maximum protocol version that this client can support. + + + + + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | int | +| Access Type | Get | + + + + + + + + + +## Nonce + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 10, version 1511 [10.0.10586] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/Nonce +``` + + + + +Enables MDMs to protect the device health attestation communications from man-in-the-middle type (MITM) attacks with a crypt-protected random value that is generated by the MDM Server. The nonce is in hex format, with a minimum size of 8 bytes, and a maximum size of 32 bytes. + + + + + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | chr (string) | +| Access Type | Get, Replace | +| Default Value | \0 | + + + + + + + + + +## PreferredMaxProtocolVersion + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 10, version 1709 [10.0.16299] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/PreferredMaxProtocolVersion +``` + + + + +Provides the maximum preferred protocol version that the client is configured to communicate over. If this is higher than the protocol versions supported by the client it will use the highest protocol version available to it. + + + + + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | int | +| Access Type | Get, Replace | +| Default Value | 3 | + + + + + + + + + +## Status + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 10, version 1511 [10.0.10586] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/Status +``` + + + + +Provides the current status of the device health request. For the complete list of status values, see [HealthAttestation CSP status and error codes](#healthattestation-csp-status-and-error-codes) + + + + + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | int | +| Access Type | Get | + + + + + + + + + +## TpmReadyStatus + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 10, version 1607 [10.0.14393] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/TpmReadyStatus +``` + + + + +Returns a bitmask of information describing the state of TPM. It indicates whether the TPM of the device is in a ready and trusted state. + + + + + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | int | +| Access Type | Get | + + + + + + + + + +## TriggerAttestation + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 11, version 21H2 [10.0.22000] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/TriggerAttestation +``` + + + + +Notifies the device to trigger an attestation session asynchronously. + + + + +If the attestation process is launched successfully, this node will return code 202 indicating the request is received and being processed. Otherwise, an error will be returned. + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | chr (string) | +| Access Type | Exec | + + + + +**Example**: + +- Templated SyncML Call: + + ```xml + + + + VERIFYHEALTHV2 + + + + ./Vendor/MSFT/HealthAttestation/TriggerAttestation + + + + { + rpID : "rpID", serviceEndpoint : "MAA endpoint", + nonce : "nonce", aadToken : "aadToken", "cv" : "CorrelationVector" + } + + + + + + + ``` + +- Data fields: + + - rpID (Relying Party Identifier): This field contains an identifier that can be used to help determine the caller. + - serviceEndpoint : This field contains the complete URL of the Microsoft Azure Attestation provider instance to be used for evaluation. + - nonce: This field contains an arbitrary number that can be used only once in a cryptographic communication. It's often a random or pseudo-random number issued in an authentication protocol to ensure that old communications can't be reused in replay attacks. + - aadToken: The Azure Active Directory token to be used for authentication against the Microsoft Azure Attestation service. + - cv: This field contains an identifier(Correlation Vector) that will be passed in to the service call, and that can be used for diagnostics purposes. + +- Sample ``: + + ```json + { + "rpid" : "https://www.contoso.com/attestation", + "endpoint" : "https://contoso.eus.attest.azure.net/attest/tpm?api-version=2020-10-01", + "nonce" : "5468697320697320612054657374204e6f6e6365", + "aadToken" : "dummytokenstring", + "cv" : "testonboarded" + } + ``` + + + + + +## VerifyHealth + + +| Scope | Editions | Applicable OS | +|:--|:--|:--| +| :heavy_check_mark: Device
:x: User | :x: Home
:heavy_check_mark: Pro
:heavy_check_mark: Enterprise
:heavy_check_mark: Education
:heavy_check_mark: Windows SE | :heavy_check_mark: Windows 10, version 1511 [10.0.10586] and later | + + + +```Device +./Vendor/MSFT/HealthAttestation/VerifyHealth +``` + + + + +Notifies the device to prepare a device health verification request. + + + + + + + +**Description framework properties**: + +| Property name | Property value | +|:--|:--| +| Format | null | +| Access Type | Exec | + + + + + + + + + + ## Windows 11 Device health attestation Windows 11 introduces an update to the device health attestation feature. This update helps add support for deeper insights to Windows boot security, supporting a zero trust approach to device security. Device health attestation on Windows can be accessed by using the HealthAttestation CSP. This CSP helps assess if a device is booted to a trusted and compliant state and then to take appropriate action. Windows 11 introduces more child nodes to the HealthAttestation node for the MDM providers to connect to the Microsoft Azure Attestation service, which provides a simplified approach to attestation. The attestation report provides a health assessment of the boot-time properties of the device to ensure that the devices are automatically secure as soon as they power on. The health attestation result can then be used to allow or deny access to networks, apps, or services, depending on the health of the device. -### Terms +Terms used: - **TPM (Trusted Platform Module)**: TPM is a specialized hardware-protected logic that performs a series of hardware protected security operations including providing protected storage, random number generation, encryption, and signing. - - **DHA (Device HealthAttestation) feature**: The Device HealthAttestation (DHA) feature enables enterprise IT administrators to monitor the security posture of managed devices remotely by using hardware (TPM) protected and attested data via a tamper-resistant and tamper-evident communication channel. - - **MAA-Session (Microsoft Azure Attestation service based device HealthAttestation session)**: The Microsoft Azure Attestation service-based device HealthAttestation session (MAA-Session) describes the end-to-end communication flow that is performed in one device health attestation session. - -- **MAA-CSP Nodes (Microsoft Azure Attestation based Configuration Service Provider)**: The Configuration Service Provider nodes added to Windows 11 to integrate with Microsoft Azure Attestation Service. - - The following list of operations is performed by MAA-CSP: - +- **MAA-CSP Nodes (Microsoft Azure Attestation based Configuration Service Provider)**: The Configuration Service Provider nodes added to Windows 11 to integrate with Microsoft Azure Attestation Service. The following list of operations is performed by MAA-CSP: - Receives attestation trigger requests from a HealthAttestation enabled MDM provider. - The device collects Attestation Evidence (device boot logs, TPM audit trails and the TPM certificate) from a managed device. - Forwards the Attestation Evidence to the Azure Attestation Service instance as configured by the MDM provider. - Receives a signed report from the Azure Attestation Service instance and stores it in a local cache on the device. - - **MAA endpoint**: Microsoft Azure attestation service is an Azure resource, and every instance of the service gets administrator configured URL. The URI generated is unique in nature and for the purposes of device health attestation is known as the MAA endpoint. - - **JWT (JSON Web Token)**: JSON Web Token (JWT) is an open standard RFC7519 method for securely transmitting information between parties as a JavaScript Object Notation (JSON) object. This information can be verified and trusted because it's digitally signed. JWTs can be signed using a secret or a public/private key pair. ### Attestation Flow with Microsoft Azure Attestation Service @@ -72,197 +816,6 @@ Attestation flow can be broadly in three main steps: For more information, see [Attestation Protocol](/azure/attestation/virtualization-based-security-protocol). -### Configuration Service Provider Nodes - -Windows 11 introduces additions to the HealthAttestation CSP node to integrate with Microsoft Azure Attestation service. - -```console -./Vendor/MSFT -HealthAttestation -----... -----TriggerAttestation | -----AttestStatus | Added in Windows 11 -----GetAttestReport | -----GetServiceCorrelationIDs | -----VerifyHealth -----Status -----ForceRetrieve -----Certificate -----Nonce -----CorrelationID -----HASEndpoint -----TpmReadyStatus -----CurrentProtocolVersion -----PreferredMaxProtocolVersion -----MaxSupportedProtocolVersion -``` - -**./Vendor/MSFT/HealthAttestation** - -The root node for the device HealthAttestation configuration service provider. - -**TriggerAttestation** (Required) - -Node type: EXECUTE - -This node will trigger attestation flow by launching an attestation process. If the attestation process is launched successfully, this node will return code 202 indicating the request is received and being processed. Otherwise, an error will be returned. - -Templated SyncML Call: - -```xml - - - - VERIFYHEALTHV2 - - - - ./Vendor/MSFT/HealthAttestation/TriggerAttestation - - - - { - rpID : "rpID", serviceEndpoint : "MAA endpoint", - nonce : "nonce", aadToken : "aadToken", "cv" : "CorrelationVector" - } - - - - - - -``` - -Data fields: - -- rpID (Relying Party Identifier): This field contains an identifier that can be used to help determine the caller. -- serviceEndpoint : This field contains the complete URL of the Microsoft Azure Attestation provider instance to be used for evaluation. -- nonce: This field contains an arbitrary number that can be used only once in a cryptographic communication. It's often a random or pseudo-random number issued in an authentication protocol to ensure that old communications can't be reused in replay attacks. -- aadToken: The Azure Active Directory token to be used for authentication against the Microsoft Azure Attestation service. -- cv: This field contains an identifier(Correlation Vector) that will be passed in to the service call, and that can be used for diagnostics purposes. - -Sample Data: - -```json - -{ -"rpid" : "https://www.contoso.com/attestation", -"endpoint" : "https://contoso.eus.attest.azure.net/attest/tpm?api-version=2020-10-01", -"nonce" : "5468697320697320612054657374204e6f6e6365", -"aadToken" : "dummytokenstring", -"cv" : "testonboarded" -} - -``` - -**AttestStatus** - -Node type: GET - -This node will retrieve the status(HRESULT value) stored in registry updated by the attestation process triggered in the previous step. -The status is always cleared prior to making the attest service call. - -Templated SyncML Call: - -```xml - - - - - - - ./Device/Vendor/MSFT/HealthAttestation/AttestStatus - - - - - - - -``` - -Sample Data: - -```console -If Successful: 0 -If Failed: A corresponding HRESULT error code -Example: 0x80072efd, WININET_E_CANNOT_CONNECT -``` - -**GetAttestReport** - -Node type: GET - -This node will retrieve the attestation report per the call made by the TriggerAttestation, if there's any, for the given MDM provider. The report is stored in a registry key in the respective MDM enrollment store. - -Templated SyncML Call: - -```xml - - - - - - - ./Device/Vendor/MSFT/HealthAttestation/GetAttestReport - - - - - - - -``` - -Sample data: - -```console -If Success: -JWT token: aaaaaaaaaaaaa.bbbbbbbbbbbbb.cccccccccc -If failed: -Previously cached report if available (the token may have already expired per the attestation policy). -OR Sync ML 404 error if not cached report available. -``` - -**GetServiceCorrelationIDs** - -Node type: GET - -This node will retrieve the service-generated correlation IDs for the given MDM provider. If there's more than one correlation ID, they're separated by “;” in the string. - -Templated SyncML Call: - -```xml - - - - - - - ./Device/Vendor/MSFT/HealthAttestation/GetServiceCorrelationIDs - - - - - - - -``` - -Sample data: - -```console -If success: -GUID returned by the attestation service: 1k9+vQOn00S8ZK33;CMc969r1JEuHwDpM -If Trigger Attestation call failed and no previous data is present. The field remains empty. -Otherwise, the last service correlation id will be returned. In a successful attestation there are two -calls between client and MAA and for each call the GUID is separated by semicolon. -``` - -> [!NOTE] -> MAA CSP nodes are available on arm64 but isn't currently supported. - - ### MAA CSP Integration Steps 1. Set up an MAA provider instance: MAA instance can be created following the steps at [Quickstart: Set up Azure Attestation by using the Azure portal](/azure/attestation/quickstart-portal). @@ -278,136 +831,136 @@ calls between client and MAA and for each call the GUID is separated by semicolo }; authorizationrules { - => permit(); + => permit(); }; - issuancerules{ + issuancerules { - // SecureBoot enabled - c:[type == "events", issuer=="AttestationService"] => add(type = "efiConfigVariables", value = JmesPath(c.value, "Events[?EventTypeString == 'EV_EFI_VARIABLE_DRIVER_CONFIG' && ProcessedData.VariableGuid == '8BE4DF61-93CA-11D2-AA0D-00E098032B8C']")); - c:[type == "efiConfigVariables", issuer=="AttestationPolicy"]=> issue(type = "secureBootEnabled", value = JsonToClaimValue(JmesPath(c.value, "[?ProcessedData.UnicodeName == 'SecureBoot'] | length(@) == `1` && @[0].ProcessedData.VariableData == 'AQ'"))); - ![type=="secureBootEnabled", issuer=="AttestationPolicy"] => issue(type="secureBootEnabled", value=false); + // SecureBoot enabled + c:[type == "events", issuer=="AttestationService"] => add(type = "efiConfigVariables", value = JmesPath(c.value, "Events[?EventTypeString == 'EV_EFI_VARIABLE_DRIVER_CONFIG' && ProcessedData.VariableGuid == '8BE4DF61-93CA-11D2-AA0D-00E098032B8C']")); + c:[type == "efiConfigVariables", issuer=="AttestationPolicy"]=> issue(type = "secureBootEnabled", value = JsonToClaimValue(JmesPath(c.value, "[?ProcessedData.UnicodeName == 'SecureBoot'] | length(@) == `1` && @[0].ProcessedData.VariableData == 'AQ'"))); + ![type=="secureBootEnabled", issuer=="AttestationPolicy"] => issue(type="secureBootEnabled", value=false); - // Retrieve bool properties - c:[type=="events", issuer=="AttestationService"] => add(type="boolProperties", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && (PcrIndex == `12` || PcrIndex == `13` || PcrIndex == `19` || PcrIndex == `20`)].ProcessedData.EVENT_TRUSTBOUNDARY")); - c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="codeIntegrityEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_CODEINTEGRITY"))); - c:[type=="codeIntegrityEnabledSet", issuer=="AttestationPolicy"] => issue(type="codeIntegrityEnabled", value=ContainsOnlyValue(c.value, true)); - ![type=="codeIntegrityEnabled", issuer=="AttestationPolicy"] => issue(type="codeIntegrityEnabled", value=false); + // Retrieve bool properties + c:[type=="events", issuer=="AttestationService"] => add(type="boolProperties", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && (PcrIndex == `12` || PcrIndex == `13` || PcrIndex == `19` || PcrIndex == `20`)].ProcessedData.EVENT_TRUSTBOUNDARY")); + c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="codeIntegrityEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_CODEINTEGRITY"))); + c:[type=="codeIntegrityEnabledSet", issuer=="AttestationPolicy"] => issue(type="codeIntegrityEnabled", value=ContainsOnlyValue(c.value, true)); + ![type=="codeIntegrityEnabled", issuer=="AttestationPolicy"] => issue(type="codeIntegrityEnabled", value=false); - // Bitlocker Boot Status, The first non zero measurement or zero. - c:[type=="events", issuer=="AttestationService"] => add(type="srtmDrtmEventPcr", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && (PcrIndex == `12` || PcrIndex == `19`)].ProcessedData.EVENT_TRUSTBOUNDARY")); - c:[type=="srtmDrtmEventPcr", issuer=="AttestationPolicy"] => issue(type="bitlockerEnabledValue", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_BITLOCKER_UNLOCK | @[? Value != `0`].Value | @[0]"))); - [type=="bitlockerEnabledValue"] => issue(type="bitlockerEnabled", value=true); - ![type=="bitlockerEnabledValue"] => issue(type="bitlockerEnabled", value=false); + // Bitlocker Boot Status, The first non zero measurement or zero. + c:[type=="events", issuer=="AttestationService"] => add(type="srtmDrtmEventPcr", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && (PcrIndex == `12` || PcrIndex == `19`)].ProcessedData.EVENT_TRUSTBOUNDARY")); + c:[type=="srtmDrtmEventPcr", issuer=="AttestationPolicy"] => issue(type="bitlockerEnabledValue", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_BITLOCKER_UNLOCK | @[? Value != `0`].Value | @[0]"))); + [type=="bitlockerEnabledValue"] => issue(type="bitlockerEnabled", value=true); + ![type=="bitlockerEnabledValue"] => issue(type="bitlockerEnabled", value=false); - // Elam Driver (windows defender) Loaded - c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="elamDriverLoaded", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_LOADEDMODULE_AGGREGATION[] | [? EVENT_IMAGEVALIDATED == `true` && (equals_ignore_case(EVENT_FILEPATH, '\\windows\\system32\\drivers\\wdboot.sys') || equals_ignore_case(EVENT_FILEPATH, '\\windows\\system32\\drivers\\wd\\wdboot.sys'))] | @ != `null`"))); - [type=="elamDriverLoaded", issuer=="AttestationPolicy"] => issue(type="WindowsDefenderElamDriverLoaded", value=true); - ![type=="elamDriverLoaded", issuer=="AttestationPolicy"] => issue(type="WindowsDefenderElamDriverLoaded", value=false); + // Elam Driver (windows defender) Loaded + c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="elamDriverLoaded", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_LOADEDMODULE_AGGREGATION[] | [? EVENT_IMAGEVALIDATED == `true` && (equals_ignore_case(EVENT_FILEPATH, '\\windows\\system32\\drivers\\wdboot.sys') || equals_ignore_case(EVENT_FILEPATH, '\\windows\\system32\\drivers\\wd\\wdboot.sys'))] | @ != `null`"))); + [type=="elamDriverLoaded", issuer=="AttestationPolicy"] => issue(type="WindowsDefenderElamDriverLoaded", value=true); + ![type=="elamDriverLoaded", issuer=="AttestationPolicy"] => issue(type="WindowsDefenderElamDriverLoaded", value=false); - // Boot debugging - c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="bootDebuggingEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_BOOTDEBUGGING"))); - c:[type=="bootDebuggingEnabledSet", issuer=="AttestationPolicy"] => issue(type="bootDebuggingDisabled", value=ContainsOnlyValue(c.value, false)); - ![type=="bootDebuggingDisabled", issuer=="AttestationPolicy"] => issue(type="bootDebuggingDisabled", value=false); + // Boot debugging + c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="bootDebuggingEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_BOOTDEBUGGING"))); + c:[type=="bootDebuggingEnabledSet", issuer=="AttestationPolicy"] => issue(type="bootDebuggingDisabled", value=ContainsOnlyValue(c.value, false)); + ![type=="bootDebuggingDisabled", issuer=="AttestationPolicy"] => issue(type="bootDebuggingDisabled", value=false); - // Kernel Debugging - c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="osKernelDebuggingEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_OSKERNELDEBUG"))); - c:[type=="osKernelDebuggingEnabledSet", issuer=="AttestationPolicy"] => issue(type="osKernelDebuggingDisabled", value=ContainsOnlyValue(c.value, false)); - ![type=="osKernelDebuggingDisabled", issuer=="AttestationPolicy"] => issue(type="osKernelDebuggingDisabled", value=false); + // Kernel Debugging + c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="osKernelDebuggingEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_OSKERNELDEBUG"))); + c:[type=="osKernelDebuggingEnabledSet", issuer=="AttestationPolicy"] => issue(type="osKernelDebuggingDisabled", value=ContainsOnlyValue(c.value, false)); + ![type=="osKernelDebuggingDisabled", issuer=="AttestationPolicy"] => issue(type="osKernelDebuggingDisabled", value=false); - // DEP Policy - c:[type=="boolProperties", issuer=="AttestationPolicy"] => issue(type="depPolicy", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_DATAEXECUTIONPREVENTION.Value | @[-1]"))); - ![type=="depPolicy"] => issue(type="depPolicy", value=0); + // DEP Policy + c:[type=="boolProperties", issuer=="AttestationPolicy"] => issue(type="depPolicy", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_DATAEXECUTIONPREVENTION.Value | @[-1]"))); + ![type=="depPolicy"] => issue(type="depPolicy", value=0); - // Test Signing - c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="testSigningEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_TESTSIGNING"))); - c:[type=="testSigningEnabledSet", issuer=="AttestationPolicy"] => issue(type="testSigningDisabled", value=ContainsOnlyValue(c.value, false)); - ![type=="testSigningDisabled", issuer=="AttestationPolicy"] => issue(type="testSigningDisabled", value=false); + // Test Signing + c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="testSigningEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_TESTSIGNING"))); + c:[type=="testSigningEnabledSet", issuer=="AttestationPolicy"] => issue(type="testSigningDisabled", value=ContainsOnlyValue(c.value, false)); + ![type=="testSigningDisabled", issuer=="AttestationPolicy"] => issue(type="testSigningDisabled", value=false); - // Flight Signing - c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="flightSigningEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_FLIGHTSIGNING"))); - c:[type=="flightSigningEnabledSet", issuer=="AttestationPolicy"] => issue(type="flightSigningNotEnabled", value=ContainsOnlyValue(c.value, false)); - ![type=="flightSigningNotEnabled", issuer=="AttestationPolicy"] => issue(type="flightSigningNotEnabled", value=false); + // Flight Signing + c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="flightSigningEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_FLIGHTSIGNING"))); + c:[type=="flightSigningEnabledSet", issuer=="AttestationPolicy"] => issue(type="flightSigningNotEnabled", value=ContainsOnlyValue(c.value, false)); + ![type=="flightSigningNotEnabled", issuer=="AttestationPolicy"] => issue(type="flightSigningNotEnabled", value=false); - // VSM enabled - c:[type=="events", issuer=="AttestationService"] => add(type="srtmDrtmEventPcr", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && (PcrIndex == `12` || PcrIndex == `19`)].ProcessedData.EVENT_TRUSTBOUNDARY")); - c:[type=="srtmDrtmEventPcr", issuer=="AttestationPolicy"] => add(type="vbsEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_VBS_VSM_REQUIRED"))); - c:[type=="srtmDrtmEventPcr", issuer=="AttestationPolicy"] => add(type="vbsEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_VBS_MANDATORY_ENFORCEMENT"))); - c:[type=="vbsEnabledSet", issuer=="AttestationPolicy"] => issue(type="vbsEnabled", value=ContainsOnlyValue(c.value, true)); - ![type=="vbsEnabled", issuer=="AttestationPolicy"] => issue(type="vbsEnabled", value=false); - c:[type=="vbsEnabled", issuer=="AttestationPolicy"] => issue(type="vbsEnabled", value=c.value); + // VSM enabled + c:[type=="events", issuer=="AttestationService"] => add(type="srtmDrtmEventPcr", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && (PcrIndex == `12` || PcrIndex == `19`)].ProcessedData.EVENT_TRUSTBOUNDARY")); + c:[type=="srtmDrtmEventPcr", issuer=="AttestationPolicy"] => add(type="vbsEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_VBS_VSM_REQUIRED"))); + c:[type=="srtmDrtmEventPcr", issuer=="AttestationPolicy"] => add(type="vbsEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_VBS_MANDATORY_ENFORCEMENT"))); + c:[type=="vbsEnabledSet", issuer=="AttestationPolicy"] => issue(type="vbsEnabled", value=ContainsOnlyValue(c.value, true)); + ![type=="vbsEnabled", issuer=="AttestationPolicy"] => issue(type="vbsEnabled", value=false); + c:[type=="vbsEnabled", issuer=="AttestationPolicy"] => issue(type="vbsEnabled", value=c.value); - // HVCI - c:[type=="srtmDrtmEventPcr", issuer=="AttestationPolicy"] => add(type="hvciEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_VBS_HVCI_POLICY | @[?String == 'HypervisorEnforcedCodeIntegrityEnable'].Value"))); - c:[type=="hvciEnabledSet", issuer=="AttestationPolicy"] => issue(type="hvciEnabled", value=ContainsOnlyValue(c.value, 1)); - ![type=="hvciEnabled", issuer=="AttestationPolicy"] => issue(type="hvciEnabled", value=false); + // HVCI + c:[type=="srtmDrtmEventPcr", issuer=="AttestationPolicy"] => add(type="hvciEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_VBS_HVCI_POLICY | @[?String == 'HypervisorEnforcedCodeIntegrityEnable'].Value"))); + c:[type=="hvciEnabledSet", issuer=="AttestationPolicy"] => issue(type="hvciEnabled", value=ContainsOnlyValue(c.value, 1)); + ![type=="hvciEnabled", issuer=="AttestationPolicy"] => issue(type="hvciEnabled", value=false); - // IOMMU - c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="iommuEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_VBS_IOMMU_REQUIRED"))); - c:[type=="iommuEnabledSet", issuer=="AttestationPolicy"] => issue(type="iommuEnabled", value=ContainsOnlyValue(c.value, true)); - ![type=="iommuEnabled", issuer=="AttestationPolicy"] => issue(type="iommuEnabled", value=false); + // IOMMU + c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="iommuEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_VBS_IOMMU_REQUIRED"))); + c:[type=="iommuEnabledSet", issuer=="AttestationPolicy"] => issue(type="iommuEnabled", value=ContainsOnlyValue(c.value, true)); + ![type=="iommuEnabled", issuer=="AttestationPolicy"] => issue(type="iommuEnabled", value=false); - // Find the Boot Manager SVN, this is measured as part of a sequence and find the various measurements - // Find the first EV_SEPARATOR in PCR 12, 13, Or 14 - c:[type=="events", issuer=="AttestationService"] => add(type="evSeparatorSeq", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_SEPARATOR' && (PcrIndex == `12` || PcrIndex == `13` || PcrIndex == `14`)] | @[0].EventSeq")); - c:[type=="evSeparatorSeq", value != "null", issuer=="AttestationPolicy"] => add(type="beforeEvSepClause", value=AppendString(AppendString("Events[? EventSeq < `", c.value), "`")); - [type=="evSeparatorSeq", value=="null", issuer=="AttestationPolicy"] => add(type="beforeEvSepClause", value="Events[? `true` "); + // Find the Boot Manager SVN, this is measured as part of a sequence and find the various measurements + // Find the first EV_SEPARATOR in PCR 12, 13, Or 14 + c:[type=="events", issuer=="AttestationService"] => add(type="evSeparatorSeq", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_SEPARATOR' && (PcrIndex == `12` || PcrIndex == `13` || PcrIndex == `14`)] | @[0].EventSeq")); + c:[type=="evSeparatorSeq", value != "null", issuer=="AttestationPolicy"] => add(type="beforeEvSepClause", value=AppendString(AppendString("Events[? EventSeq < `", c.value), "`")); + [type=="evSeparatorSeq", value=="null", issuer=="AttestationPolicy"] => add(type="beforeEvSepClause", value="Events[? `true` "); - // Find the first EVENT_APPLICATION_SVN. - c:[type=="beforeEvSepClause", issuer=="AttestationPolicy"] => add(type="bootMgrSvnSeqQuery", value=AppendString(c.value, " && EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `12` && ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_APPLICATION_SVN] | @[0].EventSeq")); - c1:[type=="bootMgrSvnSeqQuery", issuer=="AttestationPolicy"] && c2:[type=="events", issuer=="AttestationService"] => add(type="bootMgrSvnSeq", value=JmesPath(c2.value, c1.value)); - c:[type=="bootMgrSvnSeq", value!="null", issuer=="AttestationPolicy"] => add(type="bootMgrSvnQuery", value=AppendString(AppendString("Events[? EventSeq == `", c.value), "`].ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_APPLICATION_SVN | @[0]")); + // Find the first EVENT_APPLICATION_SVN. + c:[type=="beforeEvSepClause", issuer=="AttestationPolicy"] => add(type="bootMgrSvnSeqQuery", value=AppendString(c.value, " && EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `12` && ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_APPLICATION_SVN] | @[0].EventSeq")); + c1:[type=="bootMgrSvnSeqQuery", issuer=="AttestationPolicy"] && c2:[type=="events", issuer=="AttestationService"] => add(type="bootMgrSvnSeq", value=JmesPath(c2.value, c1.value)); + c:[type=="bootMgrSvnSeq", value!="null", issuer=="AttestationPolicy"] => add(type="bootMgrSvnQuery", value=AppendString(AppendString("Events[? EventSeq == `", c.value), "`].ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_APPLICATION_SVN | @[0]")); - // The first EVENT_APPLICATION_SVN. That value is the Boot Manager SVN - c1:[type=="bootMgrSvnQuery", issuer=="AttestationPolicy"] && c2:[type=="events", issuer=="AttestationService"] => issue(type="bootMgrSvn", value=JsonToClaimValue(JmesPath(c2.value, c1.value))); + // The first EVENT_APPLICATION_SVN. That value is the Boot Manager SVN + c1:[type=="bootMgrSvnQuery", issuer=="AttestationPolicy"] && c2:[type=="events", issuer=="AttestationService"] => issue(type="bootMgrSvn", value=JsonToClaimValue(JmesPath(c2.value, c1.value))); - // OS Rev List Info - c:[type=="events", issuer=="AttestationService"] => issue(type="osRevListInfo", value=JsonToClaimValue(JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `13`].ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_OS_REVOCATION_LIST.RawData | @[0]"))); + // OS Rev List Info + c:[type=="events", issuer=="AttestationService"] => issue(type="osRevListInfo", value=JsonToClaimValue(JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `13`].ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_OS_REVOCATION_LIST.RawData | @[0]"))); - // Safe mode - c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="safeModeEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_SAFEMODE"))); - c:[type=="safeModeEnabledSet", issuer=="AttestationPolicy"] => issue(type="notSafeMode", value=ContainsOnlyValue(c.value, false)); - ![type=="notSafeMode", issuer=="AttestationPolicy"] => issue(type="notSafeMode", value=true); + // Safe mode + c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="safeModeEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_SAFEMODE"))); + c:[type=="safeModeEnabledSet", issuer=="AttestationPolicy"] => issue(type="notSafeMode", value=ContainsOnlyValue(c.value, false)); + ![type=="notSafeMode", issuer=="AttestationPolicy"] => issue(type="notSafeMode", value=true); - // Win PE - c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="winPEEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_WINPE"))); - c:[type=="winPEEnabledSet", issuer=="AttestationPolicy"] => issue(type="notWinPE", value=ContainsOnlyValue(c.value, false)); - ![type=="notWinPE", issuer=="AttestationPolicy"] => issue(type="notWinPE", value=true); + // Win PE + c:[type=="boolProperties", issuer=="AttestationPolicy"] => add(type="winPEEnabledSet", value=JsonToClaimValue(JmesPath(c.value, "[*].EVENT_WINPE"))); + c:[type=="winPEEnabledSet", issuer=="AttestationPolicy"] => issue(type="notWinPE", value=ContainsOnlyValue(c.value, false)); + ![type=="notWinPE", issuer=="AttestationPolicy"] => issue(type="notWinPE", value=true); - // CI Policy - c:[type=="events", issuer=="AttestationService"] => issue(type="codeIntegrityPolicy", value=JsonToClaimValue(JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `13`].ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_SI_POLICY[].RawData"))); + // CI Policy + c:[type=="events", issuer=="AttestationService"] => issue(type="codeIntegrityPolicy", value=JsonToClaimValue(JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `13`].ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_SI_POLICY[].RawData"))); - // Secure Boot Custom Policy - c:[type=="events", issuer=="AttestationService"] => issue(type="secureBootCustomPolicy", value=JsonToClaimValue(JmesPath(c.value, "Events[? EventTypeString == 'EV_EFI_VARIABLE_DRIVER_CONFIG' && PcrIndex == `7` && ProcessedData.UnicodeName == 'CurrentPolicy' && ProcessedData.VariableGuid == '77FA9ABD-0359-4D32-BD60-28F4E78F784B'].ProcessedData.VariableData | @[0]"))); + // Secure Boot Custom Policy + c:[type=="events", issuer=="AttestationService"] => issue(type="secureBootCustomPolicy", value=JsonToClaimValue(JmesPath(c.value, "Events[? EventTypeString == 'EV_EFI_VARIABLE_DRIVER_CONFIG' && PcrIndex == `7` && ProcessedData.UnicodeName == 'CurrentPolicy' && ProcessedData.VariableGuid == '77FA9ABD-0359-4D32-BD60-28F4E78F784B'].ProcessedData.VariableData | @[0]"))); - // Find the first EV_SEPARATOR in PCR 12, 13, Or 14 - c:[type=="events", issuer=="AttestationService"] => add(type="evSeparatorSeq", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_SEPARATOR' && (PcrIndex == `12` || PcrIndex == `13` || PcrIndex == `14`)] | @[0].EventSeq")); - c:[type=="evSeparatorSeq", value != "null", issuer=="AttestationPolicy"] => add(type="beforeEvSepClause", value=AppendString(AppendString("Events[? EventSeq < `", c.value), "`")); - [type=="evSeparatorSeq", value=="null", issuer=="AttestationPolicy"] => add(type="beforeEvSepClause", value="Events[? `true` "); // No restriction of EV_SEPARATOR in case it's not present + // Find the first EV_SEPARATOR in PCR 12, 13, Or 14 + c:[type=="events", issuer=="AttestationService"] => add(type="evSeparatorSeq", value=JmesPath(c.value, "Events[? EventTypeString == 'EV_SEPARATOR' && (PcrIndex == `12` || PcrIndex == `13` || PcrIndex == `14`)] | @[0].EventSeq")); + c:[type=="evSeparatorSeq", value != "null", issuer=="AttestationPolicy"] => add(type="beforeEvSepClause", value=AppendString(AppendString("Events[? EventSeq < `", c.value), "`")); + [type=="evSeparatorSeq", value=="null", issuer=="AttestationPolicy"] => add(type="beforeEvSepClause", value="Events[? `true` "); // No restriction of EV_SEPARATOR in case it's not present - //Finding the Boot App SVN - // Find the first EVENT_TRANSFER_CONTROL with value 1 or 2 in PCR 12 which is before the EV_SEPARATOR - c1:[type=="beforeEvSepClause", issuer=="AttestationPolicy"] && c2:[type=="bootMgrSvnSeq", value != "null", issuer=="AttestationPolicy"] => add(type="beforeEvSepAfterBootMgrSvnClause", value=AppendString(AppendString(AppendString(c1.value, "&& EventSeq >= `"), c2.value), "`")); - c:[type=="beforeEvSepAfterBootMgrSvnClause", issuer=="AttestationPolicy"] => add(type="tranferControlQuery", value=AppendString(c.value, " && EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `12`&& (ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_TRANSFER_CONTROL.Value == `1` || ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_TRANSFER_CONTROL.Value == `2`)] | @[0].EventSeq")); - c1:[type=="tranferControlQuery", issuer=="AttestationPolicy"] && c2:[type=="events", issuer=="AttestationService"] => add(type="tranferControlSeq", value=JmesPath(c2.value, c1.value)); + //Finding the Boot App SVN + // Find the first EVENT_TRANSFER_CONTROL with value 1 or 2 in PCR 12 which is before the EV_SEPARATOR + c1:[type=="beforeEvSepClause", issuer=="AttestationPolicy"] && c2:[type=="bootMgrSvnSeq", value != "null", issuer=="AttestationPolicy"] => add(type="beforeEvSepAfterBootMgrSvnClause", value=AppendString(AppendString(AppendString(c1.value, "&& EventSeq >= `"), c2.value), "`")); + c:[type=="beforeEvSepAfterBootMgrSvnClause", issuer=="AttestationPolicy"] => add(type="tranferControlQuery", value=AppendString(c.value, " && EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `12`&& (ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_TRANSFER_CONTROL.Value == `1` || ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_TRANSFER_CONTROL.Value == `2`)] | @[0].EventSeq")); + c1:[type=="tranferControlQuery", issuer=="AttestationPolicy"] && c2:[type=="events", issuer=="AttestationService"] => add(type="tranferControlSeq", value=JmesPath(c2.value, c1.value)); - // Find the first non-null EVENT_MODULE_SVN in PCR 13 after the transfer control. - c:[type=="tranferControlSeq", value!="null", issuer=="AttestationPolicy"] => add(type="afterTransferCtrlClause", value=AppendString(AppendString(" && EventSeq > `", c.value), "`")); - c1:[type=="beforeEvSepClause", issuer=="AttestationPolicy"] && c2:[type=="afterTransferCtrlClause", issuer=="AttestationPolicy"] => add(type="moduleQuery", value=AppendString(AppendString(c1.value, c2.value), " && EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `13` && ((ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_LOADEDMODULE_AGGREGATION[].EVENT_MODULE_SVN | @[0]) || (ProcessedData.EVENT_LOADEDMODULE_AGGREGATION[].EVENT_MODULE_SVN | @[0]))].EventSeq | @[0]")); - c1:[type=="moduleQuery", issuer=="AttestationPolicy"] && c2:[type=="events", issuer=="AttestationService"] => add(type="moduleSeq", value=JmesPath(c2.value, c1.value)); + // Find the first non-null EVENT_MODULE_SVN in PCR 13 after the transfer control. + c:[type=="tranferControlSeq", value!="null", issuer=="AttestationPolicy"] => add(type="afterTransferCtrlClause", value=AppendString(AppendString(" && EventSeq > `", c.value), "`")); + c1:[type=="beforeEvSepClause", issuer=="AttestationPolicy"] && c2:[type=="afterTransferCtrlClause", issuer=="AttestationPolicy"] => add(type="moduleQuery", value=AppendString(AppendString(c1.value, c2.value), " && EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `13` && ((ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_LOADEDMODULE_AGGREGATION[].EVENT_MODULE_SVN | @[0]) || (ProcessedData.EVENT_LOADEDMODULE_AGGREGATION[].EVENT_MODULE_SVN | @[0]))].EventSeq | @[0]")); + c1:[type=="moduleQuery", issuer=="AttestationPolicy"] && c2:[type=="events", issuer=="AttestationService"] => add(type="moduleSeq", value=JmesPath(c2.value, c1.value)); - // Find the first EVENT_APPLICATION_SVN after EV_EVENT_TAG in PCR 12. - c:[type=="moduleSeq", value!="null", issuer=="AttestationPolicy"] => add(type="applicationSvnAfterModuleClause", value=AppendString(AppendString(" && EventSeq > `", c.value), "`")); - c1:[type=="beforeEvSepClause", issuer=="AttestationPolicy"] && c2:[type=="applicationSvnAfterModuleClause", issuer=="AttestationPolicy"] => add(type="bootAppSvnQuery", value=AppendString(AppendString(c1.value, c2.value), " && EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `12`].ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_APPLICATION_SVN | @[0]")); - c1:[type=="bootAppSvnQuery", issuer=="AttestationPolicy"] && c2:[type=="events", issuer=="AttestationService"] => issue(type="bootAppSvn", value=JsonToClaimValue(JmesPath(c2.value, c1.value))); + // Find the first EVENT_APPLICATION_SVN after EV_EVENT_TAG in PCR 12. + c:[type=="moduleSeq", value!="null", issuer=="AttestationPolicy"] => add(type="applicationSvnAfterModuleClause", value=AppendString(AppendString(" && EventSeq > `", c.value), "`")); + c1:[type=="beforeEvSepClause", issuer=="AttestationPolicy"] && c2:[type=="applicationSvnAfterModuleClause", issuer=="AttestationPolicy"] => add(type="bootAppSvnQuery", value=AppendString(AppendString(c1.value, c2.value), " && EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `12`].ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_APPLICATION_SVN | @[0]")); + c1:[type=="bootAppSvnQuery", issuer=="AttestationPolicy"] && c2:[type=="events", issuer=="AttestationService"] => issue(type="bootAppSvn", value=JsonToClaimValue(JmesPath(c2.value, c1.value))); - // Finding the Boot Rev List Info - c:[type=="events", issuer=="AttestationService"] => issue(type="bootRevListInfo", value=JsonToClaimValue(JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `13`].ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_BOOT_REVOCATION_LIST.RawData | @[0]"))); + // Finding the Boot Rev List Info + c:[type=="events", issuer=="AttestationService"] => issue(type="bootRevListInfo", value=JsonToClaimValue(JmesPath(c.value, "Events[? EventTypeString == 'EV_EVENT_TAG' && PcrIndex == `13`].ProcessedData.EVENT_TRUSTBOUNDARY.EVENT_BOOT_REVOCATION_LIST.RawData | @[0]"))); }; ``` -3. Call TriggerAttestation with your rpid, Azure Active Directory token and the attestURI: Use the Attestation URL generated in step 1, and append the appropriate api version you want to hit. For more information about the api version, see [Attestation - Attest Tpm - REST API](/rest/api/attestation/attestation/attest-tpm). +3. Call TriggerAttestation with your `rpid`, `Azure Active Directory token` and the `attestURI`: Use the Attestation URL generated in step 1, and append the appropriate api version you want to hit. For more information about the api version, see [Attestation - Attest Tpm - REST API](/rest/api/attestation/attestation/attest-tpm). 4. Call GetAttestReport and decode and parse the report to ensure the attested report contains the required properties: GetAttestReport return the signed attestation token as a JWT. The JWT can be decoded to parse the information per the attestation policy. @@ -468,74 +1021,46 @@ calls between client and MAA and for each call the GUID is separated by semicolo More information about TPM attestation can be found here: [Microsoft Azure Attestation](/azure/attestation/). - ## Windows 10 Device HealthAttestation -### Terms +Terms used: - **TPM (Trusted Platform Module)**: TPM is a specialized hardware-protected logic that performs a series of hardware protected security operations including providing protected storage, random number generation, encryption, and signing. - - **DHA (Device HealthAttestation) feature**: The Device HealthAttestation (DHA) feature enables enterprise IT administrators to monitor the security posture of managed devices remotely by using hardware (TPM) protected and attested data via a tamper-resistant and tamper-evident communication channel. - - **DHA-Enabled device (Device HealthAttestation enabled device)**: A Device HealthAttestation enabled (DHA-Enabled) device is a computing device (phone, desktop, laptop, tablet, server) that runs Windows 10 and supports TPM version 1.2 or 2.0. +- **DHA-Session (Device HealthAttestation session)**: The Device HealthAttestation session (DHA-Session) describes the end-to-end communication flow that is performed in one device health attestation session. The following list of transactions is performed in one DHA-Session: -- **DHA-Session (Device HealthAttestation session)**: The Device HealthAttestation session (DHA-Session) describes the end-to-end communication flow that is performed in one device health attestation session. - - The following list of transactions is performed in one DHA-Session: + ![DHA session healthattestation session diagram](./images/HealthAttestation_1.png) - DHA-CSP and DHA-Service communication: - DHA-CSP forwards device boot data (DHA-BootData) to DHA-Service - DHA-Service replies with an encrypted data blob (DHA-EncBlob) - - DHA-CSP and MDM-Server communication: - MDM-Server sends a device health verification request to DHA-CSP - DHA-CSP replies with a payload called DHA-Data that includes an encrypted (DHA-EncBlob) and a signed (DHA-SignedBlob) data blob - - MDM-Server and DHA-Service communication: - MDM-Server posts data it receives from devices to DHA-Service - DHA-Service reviews the data it receives, and replies with a device health report (DHA-Report) - - ![DHA session healthattestation session diagram](./images/HealthAttestation_1.png) - - **DHA session data (Device HealthAttestation session data)**: The following list of data is produced or consumed in one DHA-Transaction: - - DHA-BootData: the device boot data (TCG logs, PCR values, device/TPM certificate, boot, and TPM counters) that are required for validating device boot health. - DHA-EncBlob: an encrypted summary report that DHA-Service issues to a device after reviewing the DHA-BootData it receives from devices. - - DHA-SignedBlob: it's a signed snapshot of the current state of a device’s runtime that is captured by DHA-CSP at device health attestation time. + - DHA-SignedBlob: it's a signed snapshot of the current state of a device's runtime that is captured by DHA-CSP at device health attestation time. - DHA-Data: an XML formatted data blob that devices forward for device health validation to DHA-Service via MDM-Server. DHA-Data has two parts: - - DHA-EncBlob: the encrypted data blob that the device receives from DHA-Service - DHA-SignedBlob: a current snapshot of the current security state of the device that is generated by DHA-CSP - - DHA-Report: the report that is issued by DHA-Service to MDM-Server - Nonce: a crypto protected number that is generated by MDM-Server, which protects the DHA-Session from man-in-the-middle type attacks - -- **DHA-Enabled MDM (Device HealthAttestation enabled device management solution)**: Device HealthAttestation enabled (DHA-Enabled) device management solution is a device management tool that is integrated with the DHA feature. - - DHA-Enabled device management solutions enable enterprise IT managers to raise the security protection bar for their managed devices based on hardware (TPM) protected data that can be trusted even if a device is compromised by advanced security threats or running a malicious (jailbroken) operating system. - - The following list of operations is performed by DHA-Enabled-MDM - +- **DHA-Enabled MDM (Device HealthAttestation enabled device management solution)**: Device HealthAttestation enabled (DHA-Enabled) device management solution is a device management tool that is integrated with the DHA feature. DHA-Enabled device management solutions enable enterprise IT managers to raise the security protection bar for their managed devices based on hardware (TPM) protected data that can be trusted even if a device is compromised by advanced security threats or running a malicious (jailbroken) operating system. The following list of operations is performed by DHA-Enabled-MDM: - Enables the DHA feature on a DHA-Enabled device - Issues device health attestation requests to enrolled/managed devices - Collects device health attestation data (DHA-Data), and sends it to Device Health Attestation Service (DHA-Service) for verification - Gets the device health report (DHA-Report) from DHA-Service, which triggers compliance action - -- **DHA-CSP (Device HealthAttestation Configuration Service Provider)**: The Device HealthAttestation Configuration Service Provider (DHA-CSP) uses a device’s TPM and firmware to measure critical security properties of the device’s BIOS and Windows boot, such that even on a system infected with kernel level malware or a rootkit, these properties can't be spoofed. - - The following list of operations is performed by DHA-CSP: - +- **DHA-CSP (Device HealthAttestation Configuration Service Provider)**: The Device HealthAttestation Configuration Service Provider (DHA-CSP) uses a device's TPM and firmware to measure critical security properties of the device's BIOS and Windows boot, such that even on a system infected with kernel level malware or a rootkit, these properties can't be spoofed. The following list of operations is performed by DHA-CSP: - Collects device boot data (DHA-BootData) from a managed device - Forwards DHA-BootData to Device Health Attestation Service (DHA-Service) - Receives an encrypted blob (DHA-EncBlob) from DHA-Service, and stores it in a local cache on the device - Receives attestation requests (DHA-Requests) from a DHA-Enabled MDM, and replies with Device Health Attestation data (DHA-Data) - -- **DHA-Service (Device HealthAttestation Service)**: Device HealthAttestation Service (DHA-Service) validates the data it receives from DHA-CSP and issues a highly trusted hardware (TPM) protected report (DHA-Report) to DHA-Enabled device management solutions through a tamper resistant and tamper evident communication channel. - - DHA-Service is available in two flavors: “DHA-Cloud” and “DHA-Server2016”. DHA-Service supports various implementation scenarios including cloud, on premises, air-gapped, and hybrid scenarios. - - The following list of operations is performed by DHA-Service: - +- **DHA-Service (Device HealthAttestation Service)**: Device HealthAttestation Service (DHA-Service) validates the data it receives from DHA-CSP and issues a highly trusted hardware (TPM) protected report (DHA-Report) to DHA-Enabled device management solutions through a tamper resistant and tamper evident communication channel. DHA-Service is available in two flavors: "DHA-Cloud" and "DHA-Server2016". DHA-Service supports various implementation scenarios including cloud, on premises, air-gapped, and hybrid scenarios. The following list of operations is performed by DHA-Service: - Receives device boot data (DHA-BootData) from a DHA-Enabled device - Forwards DHA-BootData to Device Health Attestation Service (DHA-Service) - Receives an encrypted blob (DHA-EncBlob) from DHA-Service, and stores it in a local cache on the device @@ -545,91 +1070,10 @@ More information about TPM attestation can be found here: [Microsoft Azure Attes |DHA-Service type|Description|Operation cost| |--- |--- |--- | -|Device Health Attestation – Cloud (DHA-Cloud)|DHA-Cloud is a Microsoft owned and operated DHA-Service that is:
  • Available in Windows for free
  • Running on a high-availability and geo-balanced cloud infrastructure
  • Supported by most DHA-Enabled device management solutions as the default device attestation service provider
  • Accessible to all enterprise-managed devices via following:
    • | -|Device Health Attestation – On Premise(DHA-OnPrem)|DHA-OnPrem refers to DHA-Service that is running on premises:
  • Offered to Windows Server 2016 customer (no added licensing cost for enabling/running DHA-Service)
  • Hosted on an enterprise owned and managed server device/hardware
  • Supported by 1st and 3rd party DHA-Enabled device management solution providers that support on-premises and hybrid (Cloud + OnPrem) hardware attestation scenarios
  • Accessible to all enterprise-managed devices via following settings:
    • | +|Device Health Attestation - Cloud (DHA-Cloud)|DHA-Cloud is a Microsoft owned and operated DHA-Service that is:
  • Available in Windows for free
  • Running on a high-availability and geo-balanced cloud infrastructure
  • Supported by most DHA-Enabled device management solutions as the default device attestation service provider
  • Accessible to all enterprise-managed devices via following:
    • | +|Device Health Attestation - On Premise(DHA-OnPrem)|DHA-OnPrem refers to DHA-Service that is running on premises:
  • Offered to Windows Server 2016 customer (no added licensing cost for enabling/running DHA-Service)
  • Hosted on an enterprise owned and managed server device/hardware
  • Supported by 1st and 3rd party DHA-Enabled device management solution providers that support on-premises and hybrid (Cloud + OnPrem) hardware attestation scenarios
  • Accessible to all enterprise-managed devices via following settings:
    • | |Device Health Attestation - Enterprise-Managed Cloud(DHA-EMC)|DHA-EMC refers to an enterprise-managed DHA-Service that is running as a virtual host/service on a Windows Server 2016 compatible - enterprise-managed cloud service, such as Microsoft Azure.
  • Offered to Windows Server 2016 customers with no extra licensing cost (no added licensing cost for enabling/running DHA-Service)
  • Supported by 1st and 3rd party DHA-Enabled device management solution providers that support on-premises and hybrid (Cloud + OnPrem) hardware attestation scenarios
  • Accessible to all enterprise-managed devices via following settings:
    • | -### CSP diagram and node descriptions - -The following shows the Device HealthAttestation configuration service provider in tree format. - -```console -./Vendor/MSFT -HealthAttestation -----VerifyHealth -----Status -----ForceRetrieve -----Certificate -----Nonce -----CorrelationID -----HASEndpoint -----TpmReadyStatus -----CurrentProtocolVersion -----PreferredMaxProtocolVersion -----MaxSupportedProtocolVersion -``` - -**./Vendor/MSFT/HealthAttestation** - -The root node for the device HealthAttestation configuration service provider. - -**VerifyHealth** (Required) - -Notifies the device to prepare a device health verification request. - -The supported operation is Execute. - -**Status** (Required) - -Provides the current status of the device health request. - -The supported operation is Get. - -The following list shows some examples of supported values. For the complete list of status, see [Device HealthAttestation CSP status and error codes](#device-healthattestation-csp-status-and-error-codes). - -- 0 - (HEALTHATTESTATION\_CERT\_RETRIEVAL_UNINITIALIZED): DHA-CSP is preparing a request to get a new DHA-EncBlob from DHA-Service -- 1 - (HEALTHATTESTATION\_CERT\_RETRIEVAL_REQUESTED): DHA-CSP is waiting for the DHA-Service to respond back, and issue a DHA-EncBlob to the device -- 2 - (HEALTHATTESTATION\_CERT\_RETRIEVAL_FAILED): A valid DHA-EncBlob couldn't be retrieved from the DHA-Service for reasons other than discussed in the DHA error/status codes -- 3 - (HEALTHATTESTATION\_CERT\_RETRIEVAL_COMPLETE): DHA-Data is ready for pickup - -**ForceRetrieve** (Optional) - -Instructs the client to initiate a new request to DHA-Service, and get a new DHA-EncBlob (a summary of the boot state that is issued by DHA-Service). This option should only be used if the MDM server enforces a certificate freshness policy, which needs to force a device to get a fresh encrypted blob from DHA-Service. - -Boolean value. The supported operation is Replace. - -**Certificate** (Required) - -Instructs the DHA-CSP to forward DHA-Data to the MDM server. - -Value type is b64. The supported operation is Get. - -**Nonce** (Required) - -Enables MDMs to protect the device health attestation communications from man-in-the-middle type (MITM) attacks with a crypt-protected random value that is generated by the MDM Server. - -The nonce is in hex format, with a minimum size of 8 bytes, and a maximum size of 32 bytes. - -The supported operations are Get and Replace. - -**CorrelationId** (Required) - -Identifies a unique device health attestation session. CorrelationId is used to correlate DHA-Service logs with the MDM server events and Client event logs for debug and troubleshooting. - -Value type is integer, the minimum value is - 2,147,483,648 and the maximum value is 2,147,483,647. The supported operation is Get. - -**HASEndpoint** (Optional) - -Identifies the fully qualified domain name (FQDN) of the DHA-Service that is assigned to perform attestation. If an FQDN isn't assigned, DHA-Cloud (Microsoft owned and operated cloud service) will be used as the default attestation service. - -Value type is string. The supported operations are Get and Replace. The default value is has.spserv.microsoft.com. - -**TpmReadyStatus** (Required) - -Added in Windows 10, version 1607 March service release. Returns a bitmask of information describing the state of TPM. It indicates whether the TPM of the device is in a ready and trusted state. - -Value type is integer. The supported operation is Get. - ### DHA-CSP integration steps The following list of validation and development tasks are required for integrating the Microsoft Device Health Attestation feature with a Windows Mobile device management solution (MDM): @@ -645,7 +1089,7 @@ The following list of validation and development tasks are required for integrat Each step is described in detail in the following sections of this topic. -### Step 1: Verify HTTPS access +### Step 1: Verify HTTPS access Validate that both the MDM server and the device (MDM client) can access has.spserv.microsoft.com using the TCP protocol over port 443 (HTTPS). @@ -696,12 +1140,12 @@ SSL-Session: Verify return code: 20 (unable to get local issuer certificate) ``` -### Step 2: Assign an enterprise trusted DHA-Service +### Step 2: Assign an enterprise trusted DHA-Service There are three types of DHA-Service: -- Device Health Attestation – Cloud (owned and operated by Microsoft) -- Device Health Attestation – On Premise (owned and operated by an enterprise, runs on Windows Server 2016 on premises) +- Device Health Attestation - Cloud (owned and operated by Microsoft) +- Device Health Attestation - On Premise (owned and operated by an enterprise, runs on Windows Server 2016 on premises) - Device Health Attestation - Enterprise-Managed Cloud (owned and operated by an enterprise, runs on Windows Server 2016 compatible enterprise-managed cloud) DHA-Cloud is the default setting. No further action is required if an enterprise is planning to use Microsoft DHA-Cloud as the trusted DHA-Service provider. @@ -722,7 +1166,7 @@ The following example shows a sample call that instructs a managed device to com ``` -### Step 3: Instruct client to prepare health data for verification +### Step 3: Instruct client to prepare health data for verification Send a SyncML call to start collection of the DHA-Data. @@ -748,7 +1192,7 @@ The following example shows a sample call that triggers collection and verificat ``` -### Step 4: Take action based on the client's response +### Step 4: Take action based on the client's response After the client receives the health attestation request, it sends a response. The following list describes the responses, along with a recommended action to take. @@ -774,9 +1218,9 @@ Here's a sample alert that is issued by DHA_CSP: ``` -- If the response to the status node isn't 0, 1 or 3, then troubleshoot the issue. For the complete list of status codes, see [Device HealthAttestation CSP status and error codes](#device-healthattestation-csp-status-and-error-codes). +- If the response to the status node isn't 0, 1 or 3, then troubleshoot the issue. For the complete list of status codes, see [HealthAttestation CSP status and error codes](#healthattestation-csp-status-and-error-codes). -### Step 5: Instruct the client to forward health attestation data for verification +### Step 5: Instruct the client to forward health attestation data for verification Create a call to the **Nonce**, **Certificate** and **CorrelationId** nodes, and pick up an encrypted payload that includes a health certificate and related data from the device. @@ -812,9 +1256,9 @@ Here's an example: ``` -### Step 6: Forward device health attestation data to DHA-service +### Step 6: Forward device health attestation data to DHA-service -In response to the request that was sent in the previous step, the MDM client forwards an XML formatted blob (response from ./Vendor/MSFT/HealthAttestation/Certificate node) and a call identifier called CorrelationId (response to ./Vendor/MSFT/HealthAttestation/CorrelationId node). +In response to the request that was sent in the previous step, the MDM client forwards an XML formatted blob (response from ./Vendor/MSFT/HealthAttestation/Certificate node) and a call identifier called CorrelationId (response to ./Vendor/MSFT/HealthAttestation/CorrelationId node). When the MDM-Server receives the above data, it must: @@ -836,7 +1280,8 @@ When the MDM-Server receives the above data, it must: - DHA-Cloud (Microsoft owned and operated DHA-Service) scenario: `https://has.spserv.microsoft.com/DeviceHealthAttestation/ValidateHealthCertificate/v3` - DHA-OnPrem or DHA-EMC: `https://FullyQualifiedDomainName-FDQN/DeviceHealthAttestation/ValidateHealthCertificate/v3` -### Step 7: Receive response from the DHA-service + +### Step 7: Receive response from the DHA-service When the Microsoft Device Health Attestation Service receives a request for verification, it performs the following steps: @@ -844,7 +1289,7 @@ When the Microsoft Device Health Attestation Service receives a request for veri - Validates the data it has received. - Creates a report, and shares the evaluation results to the MDM server via SSL in XML format. -### Step 8: Take appropriate policy action based on evaluation results +### Step 8: Take appropriate policy action based on evaluation results After the MDM server receives the verified data, the information can be used to make policy decisions by evaluating the data. Some possible actions would be: @@ -852,506 +1297,6 @@ After the MDM server receives the verified data, the information can be used to - Allow the device to access the resources, but flag the device for further investigation. - Prevent a device from accessing resources. -The following list of data points is verified by the DHA-Service in DHA-Report version 3: - -- [Issued](#issued ) -- [AIKPresent](#aikpresent) -- [ResetCount](#resetcount) * -- [RestartCount](#restartcount) * -- [DEPPolicy](#deppolicy) -- [BitlockerStatus](#bitlockerstatus) ** -- [BootManagerRevListVersion](#bootmanagerrevlistversion) -- [CodeIntegrityRevListVersion](#codeintegrityrevlistversion) -- [SecureBootEnabled](#securebootenabled) -- [BootDebuggingEnabled](#bootdebuggingenabled) -- [OSKernelDebuggingEnabled](#oskerneldebuggingenabled) -- [CodeIntegrityEnabled](#codeintegrityenabled) -- [TestSigningEnabled](#testsigningenabled) -- [SafeMode](#safemode) -- [WinPE](#winpe) -- [ELAMDriverLoaded](#elamdriverloaded) *** -- [VSMEnabled](#vsmenabled) -- [PCRHashAlgorithmID](#pcrhashalgorithmid) -- [BootAppSVN](#bootappsvn) -- [BootManagerSVN](#bootmanagersvn) -- [TpmVersion](#tpmversion) -- [PCR0](#pcr0) -- [SBCPHash](#sbcphash) -- [CIPolicy](#cipolicy) -- [BootRevListInfo](#bootrevlistinfo) -- [OSRevListInfo](#osrevlistinfo) -- [HealthStatusMismatchFlags](#healthstatusmismatchflags) - -\* TPM 2.0 only -\*\* Reports if BitLocker was enabled during initial boot. -\*\*\* The "Hybrid Resume" must be disabled on the device. Reports first-party ELAM "Defender" was loaded during boot. - -Each of these data points is described in further detail in the following sections, along with the recommended actions to take. - -**Issued** - -The date and time DHA-report was evaluated or issued to MDM. - -**AIKPresent** - -When an Attestation Identity Key (AIK) is present on a device, it indicates that the device has an endorsement key (EK) certificate. It can be trusted more than a device that doesn’t have an EK certificate. - -If AIKPresent = True (1), then allow access. - -If AIKPresent = False (0), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI assets. -- Allow conditional access based on other data points that are present at evaluation time. For example, other attributes on the health certificate, or a device's past activities and trust history. -- Take one of the previous actions and additionally place the device in a watch list to monitor the device more closely for potential risks. - -**ResetCount** (Reported only for devices that support TPM 2.0) - -This attribute reports the number of times a PC device has hibernated or resumed. - -**RestartCount** (Reported only for devices that support TPM 2.0) - -This attribute reports the number of times a PC device has rebooted. - -**DEPPolicy** - -A device can be trusted more if the DEP Policy is enabled on the device. - -Data Execution Prevention (DEP) Policy defines a set of hardware and software technologies that perform extra checks on memory to help prevent malicious code from running on a system. Secure boot allows a limited list on x86/amd64 and on ARM NTOS locks it to on. - -DEPPolicy can be disabled or enabled by using the following commands in WMI or a PowerShell script: - -- To disable DEP, type **bcdedit.exe /set {current} nx AlwaysOff** -- To enable DEP, type **bcdedit.exe /set {current} nx AlwaysOn** - -If DEPPolicy = 1 (On), then allow access. - -If DEPPolicy = 0 (Off), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI assets. -- Allow conditional access based on other data points that are present at evaluation time. For example, other attributes on the health certificate, or a device's past activities and trust history. -- Take one of the previous actions and additionally place the device in a watch list to monitor the device more closely for potential risks. - -DEP policy evaluation is a non binary status when queried. It is then mapped to an On/Off state. - -|DEP policy level |Description | Attestation reported level | Property value | -|--------------|-----------|------------|-------------| -|OptIn (default configuration) |Only Windows system components and services have DEP applied. | 0 | 2 | -|OptOut |DEP is enabled for all processes. Administrators can manually create a list of specific applications that do not have DEP applied. | 1 | 3 | -|AlwaysOn |DEP is enabled for all processess. | 3 | 1 | -|AlwaysOff |DEP is not enabled for any process. | 2 | 0 | - - -**BitLockerStatus** (at boot time) - -When BitLocker is reported "on" at boot time, the device is able to protect data that is stored on the drive from unauthorized access, when the system is turned off or goes to hibernation. - -Windows BitLocker Drive Encryption, encrypts all data stored on the Windows operating system volume. BitLocker uses the TPM to help protect the Windows operating system and user data and helps to ensure that a computer isn't tampered with, even if it's left unattended, lost, or stolen. - -If the computer is equipped with a compatible TPM, BitLocker uses the TPM to lock the encryption keys that protect the data. As a result, the keys can't be accessed until the TPM has verified the state of the computer. - -If BitLockerStatus = 1 (On), then allow access. - -If BitLockerStatus = 0 (Off), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI assets. -- Allow conditional access based on other data points that are present at evaluation time. For example, other attributes on the health certificate, or a device's past activities and trust history. -- Take one of the previous actions and additionally place the device in a watch list to monitor the device more closely for potential risks. - -**BootManagerRevListVersion** - -This attribute indicates the version of the Boot Manager that is running on the device, to allow you to track and manage the security of the boot sequence/environment. - -If BootManagerRevListVersion = [CurrentVersion], then allow access. - -If `BootManagerRevListVersion !`= [CurrentVersion], then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI and MBI assets. -- Place the device in a watch list to monitor the device more closely for potential risks. -- Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue. - -**CodeIntegrityRevListVersion** - -This attribute indicates the version of the code that is performing integrity checks during the boot sequence. Using this attribute can help you detect if the device is running the latest version of the code that performs integrity checks, or if it's exposed to security risks (revoked), and enforce an appropriate policy action. - -If CodeIntegrityRevListVersion = [CurrentVersion], then allow access. - -If `CodeIntegrityRevListVersion !`= [CurrentVersion], then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI and MBI assets. -- Place the device in a watch list to monitor the device more closely for potential risks. -- Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue. - -**SecureBootEnabled** - -When Secure Boot is enabled, the core components used to boot the machine must have correct cryptographic signatures that are trusted by the organization that manufactured the device. The UEFI firmware verifies this requirement before it lets the machine start. If any files have been tampered with, breaking their signature, the system won't boot. - -If SecureBootEnabled = 1 (True), then allow access. - -If SecurebootEnabled = 0 (False), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI assets. -- Allow conditional access based on other data points that are present at evaluation time. For example, other attributes on the health certificate, or a device's past activities and trust history. -- Take one of the previous actions and additionally place the device in a watch list to monitor the device more closely for potential risks. - -**BootDebuggingEnabled** - -Boot debug-enabled points to a device that is used in development and testing. Devices that are used for test and development typically are less secure: the device may run unstable code, or be configured with fewer security restrictions that is required for testing and development. - -Boot debugging can be disabled or enabled by using the following commands in WMI or a PowerShell script: - -- To disable boot debugging, type **bcdedit.exe /set {current} bootdebug off**. -- To enable boot debugging, type **bcdedit.exe /set {current} bootdebug on**. - -If BootdebuggingEnabled = 0 (False), then allow access. - -If BootDebuggingEnabled = 1 (True), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI assets. -- Place the device in a watch list to monitor the device more closely for potential risks. -- Trigger a corrective action, such as enabling VSM using WMI or a PowerShell script. - -**OSKernelDebuggingEnabled** - -OSKernelDebuggingEnabled points to a device that is used in development and testing. Devices that are used for test and development typically are less secure: they may run unstable code, or be configured with fewer security restrictions required for testing and development. - -If OSKernelDebuggingEnabled = 0 (False), then allow access. - -If OSKernelDebuggingEnabled = 1 (True), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI assets. -- Place the device in a watch list to monitor the device more closely for potential risks. -- Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue. - -**CodeIntegrityEnabled** - -When code integrity is enabled, code execution is restricted to integrity verified code. - -Code integrity is a feature that validates the integrity of a driver or system file each time it's loaded into memory. Code integrity detects whether an unsigned driver or system file is being loaded into the kernel, or whether a system file has been modified by malicious software that is being run by a user account with administrator privileges. - -On x64-based versions of the operating system, kernel-mode drivers must be digitally signed. - -If CodeIntegrityEnabled = 1 (True), then allow access. - -If CodeIntegrityEnabled = 0 (False), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI assets. -- Allow conditional access based on other data points that are present at evaluation time. For example, other attributes on the health certificate, or a device's past activities and trust history. -- Take one of the previous actions and additionally place the device in a watch list to monitor the device more closely for potential risks. - -**TestSigningEnabled** - -When test signing is enabled, the device doesn't enforce signature validation during boot, and allows the unsigned drivers (such as unsigned UEFI modules) to load during boot. - -Test signing can be disabled or enabled by using the following commands in WMI or a PowerShell script: - -- To disable boot debugging, type **bcdedit.exe /set {current} testsigning off**. -- To enable boot debugging, type **bcdedit.exe /set {current} testsigning on**. - -If TestSigningEnabled = 0 (False), then allow access. - -If TestSigningEnabled = 1 (True), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI and MBI assets. -- Place the device in a watch list to monitor the device more closely for potential risks. -- Trigger a corrective action, such as enabling test signing using WMI or a PowerShell script. - -**SafeMode** - -Safe mode is a troubleshooting option for Windows that starts your computer in a limited state. Only the basic files and drivers necessary to run Windows are started. - -If SafeMode = 0 (False), then allow access. - -If SafeMode = 1 (True), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI assets. -- Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue. - -**WinPE** - -Windows pre-installation Environment (Windows PE) is a minimal operating system with limited services that is used to prepare a computer for Windows installation, to copy disk images from a network file server, and to initiate Windows Setup. - -If WinPE = 0 (False), then allow access. - -If WinPE = 1 (True), then limit access to remote resources that are required for Windows OS installation. - -**ELAMDriverLoaded** (Windows Defender) - -To use this reporting feature, you must disable "Hybrid Resume" on the device. Early launch anti-malware (ELAM) provides protection for the computers in your network when they start up and before third-party drivers initialize. - -In the current release, this attribute only monitors/reports if a Microsoft first-party ELAM (Windows Defender) was loaded during initial boot. - -If a device is expected to use a third-party antivirus program, ignore the reported state. - -If a device is expected to use Windows Defender and ELAMDriverLoaded = 1 (True), then allow access. - -If a device is expected to use Windows Defender and ELAMDriverLoaded = 0 (False), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI assets. -- Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue. - -**Bcdedit.exe /set {current} vsmlaunchtype auto** - -If ELAMDriverLoaded = 1 (True), then allow access. - -If ELAMDriverLoaded = 0 (False), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI assets. -- Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue. - -**VSMEnabled** - -Virtual Secure Mode (VSM) is a container that protects high value assets from a compromised kernel. VSM requires about 1 GB of memory – it has enough capability to run the LSA service that is used for all authentication brokering. - -VSM can be enabled by using the following command in WMI or a PowerShell script: - -`bcdedit.exe /set {current} vsmlaunchtype auto` - -If VSMEnabled = 1 (True), then allow access. -If VSMEnabled = 0 (False), then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Disallow access to HBI assets. -- Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue - -**PCRHashAlgorithmID** - -This attribute is an informational attribute that identifies the HASH algorithm that was used by TPM; no compliance action required. - -**BootAppSVN** - -This attribute identifies the security version number of the Boot Application that was loaded during initial boot on the attested device - -If reported BootAppSVN equals an accepted value, then allow access. - -If reported BootAppSVN doesn't equal an accepted value, then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Direct the device to an enterprise honeypot, to further monitor the device's activities. - -**BootManagerSVN** - -This attribute identifies the security version number of the Boot Manager that was loaded during initial boot on the attested device. - -If reported BootManagerSVN equals an accepted value, then allow access. - -If reported BootManagerSVN doesn't equal an accepted value, then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Direct the device to an enterprise honeypot, to further monitor the device's activities. - -**TPMVersion** - -This attribute identifies the version of the TPM that is running on the attested device. TPMVersion node provides to replies "1" and "2": - -- 1 means TPM specification version 1.2 -- 2 means TPM specification version 2.0 - -Based on the reply you receive from TPMVersion node: - -- If reported TPMVersion equals an accepted value, then allow access. -- If reported TPMVersion doesn't equal an accepted value, then take one of the following actions that align with your enterprise policies: - - Disallow all access - - Direct the device to an enterprise honeypot, to further monitor the device's activities. - -**PCR0** - -The measurement that is captured in PCR[0] typically represents a consistent view of the Host Platform between boot cycles. It contains a measurement of components that are provided by the host platform manufacturer. - -Enterprise managers can create an allowlist of trusted PCR[0] values, compare the PCR[0] value of the managed devices (the value that is verified and reported by HAS) with the allowlist, and then make a trust decision based on the result of the comparison. - -If your enterprise doesn't have an allowlist of accepted PCR[0] values, then take no action. -If PCR[0] equals an accepted allowlist value, then allow access. - -If PCR[0] doesn't equal any accepted listed value, then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Direct the device to an enterprise honeypot, to further monitor the device's activities. - -**SBCPHash** - -SBCPHash is the finger print of the Custom Secure Boot Configuration Policy (SBCP) that was loaded during boot in Windows devices, except PCs. - -If SBCPHash isn't present, or is an accepted allow-listed value, then allow access. - -If SBCPHash is present in DHA-Report, and isn't an allowlisted value, then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Place the device in a watch list to monitor the device more closely for potential risks. - -**CIPolicy** - -This attribute indicates the Code Integrity policy that is controlling the security of the boot environment. - -If CIPolicy isn't present, or is an accepted allow-listed value, then allow access. - -If CIPolicy is present and isn't an allow-listed value, then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Place the device in a watch list to monitor the device more closely for potential risks. - -**BootRevListInfo** - -This attribute identifies the Boot Revision List that was loaded during initial boot on the attested device. - -If reported BootRevListInfo version equals an accepted value, then allow access. - -If reported BootRevListInfo version doesn't equal an accepted value, then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Direct the device to an enterprise honeypot, to further monitor the device's activities. - -**OSRevListInfo** - -This attribute identifies the Operating System Revision List that was loaded during initial boot on the attested device. - -If reported OSRevListInfo version equals an accepted value, then allow access. - -If reported OSRevListInfo version doesn't equal an accepted value, then take one of the following actions that align with your enterprise policies: - -- Disallow all access. -- Direct the device to an enterprise honeypot, to further monitor the device's activities. - -**HealthStatusMismatchFlags** - -HealthStatusMismatchFlags attribute appears if DHA-Service detects an integrity issue (mismatch) in the DHA-Data it receives from device management solutions, for validation. - -If an issue is detected, a list of impacted DHA-report elements will be listed under the HealthStatusMismatchFlags attribute. - -### Device HealthAttestation CSP status and error codes - -Error code: 0 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_UNINITIALIZED -Error description: This state is the initial state for devices that have never participated in a DHA-Session. - -Error code: 1 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_REQUESTED -Error description: This state signifies that MDM client’s Exec call on the node VerifyHealth has been triggered and now the OS is trying to retrieve DHA-EncBlob from DHA-Server. - -Error code: 2 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED -Error description: This state signifies that the device failed to retrieve DHA-EncBlob from DHA-Server. - -Error code: 3 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_COMPLETE -Error description: This state signifies that the device has successfully retrieved DHA-EncBlob from the DHA-Server. - -Error code: 4 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_PCR_FAIL -Error description: Deprecated in Windows 10, version 1607. - -Error code: 5 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_GETQUOTE_FAIL -Error description: DHA-CSP failed to get a claim quote. - -Error code: 6 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_DEVICE_NOT_READY -Error description: DHA-CSP failed in opening a handle to Microsoft Platform Crypto Provider. - -Error code: 7 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_WINDOWS_AIK_FAIL -Error description: DHA-CSP failed in retrieving Windows AIK - -Error code: 8 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FROM_WEB_FAIL -Error description: Deprecated in Windows 10, version 1607. - -Error code: 9 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_INVALID_TPM_VERSION -Error description: Invalid TPM version (TPM version isn't 1.2 or 2.0) - -Error code: 10 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_GETNONCE_FAIL -Error description: Nonce wasn't found in the registry. - -Error code: 11 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_GETCORRELATIONID_FAIL -Error description: Correlation ID wasn't found in the registry. - -Error code: 12 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_GETCERT_FAIL -Error description: Deprecated in Windows 10, version 1607. - -Error code: 13 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_GETCLAIM_FAIL -Error description: Deprecated in Windows 10, version 1607. - -Error code: 14 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_ENCODING_FAIL -Error description: Failure in Encoding functions. (Extremely unlikely scenario) - -Error code: 15 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_ENDPOINTOVERRIDE_FAIL -Error description: Deprecated in Windows 10, version 1607. - -Error code: 16 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_LOAD_XML -Error description: DHA-CSP failed to load the payload it received from DHA-Service - -Error code: 17 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_CORRUPT_XML -Error description: DHA-CSP received a corrupted response from DHA-Service. - -Error code: 18 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_EMPTY_XML -Error description: DHA-CSP received an empty response from DHA-Service. - -Error code: 19 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_DECRYPT_AES_EK -Error description: DHA-CSP failed in decrypting the AES key from the EK challenge. - -Error code: 20 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_DECRYPT_CERT_AES_EK -Error description: DHA-CSP failed in decrypting the health cert with the AES key. - -Error code: 21 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_EXPORT_AIKPUB -Error description: DHA-CSP failed in exporting the AIK Public Key. - -Error code: 22 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_CREATE_CLAIMAUTHORITYONLY -Error description: DHA-CSP failed in trying to create a claim with AIK attestation data. - -Error code: 23 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_APPEND_AIKPUB -Error description: DHA-CSP failed in appending the AIK Pub to the request blob. - -Error code: 24 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_APPEND_AIKCERT -Error description: DHA-CSP failed in appending the AIK Cert to the request blob. - -Error code: 25 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_INIT_HTTPHANDLE -Error description: DHA-CSP failed to obtain a Session handle. - -Error code: 26 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_GETTARGET_HTTPHANDLE -Error description: DHA-CSP failed to connect to the DHA-Service. - -Error code: 27 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_CREATE_HTTPHAND -Error description: DHA-CSP failed to create an HTTP request handle. - -Error code: 28 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_SET_INTERNETOPTION -Error description: DHA-CSP failed to set options. - -Error code: 29 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_ADD_REQUESTHEADERS -Error description: DHA-CSP failed to add request headers. - -Error code: 30 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_SEND_REQUEST -Error description: DHA-CSP failed to send the HTTP request. - -Error code: 31 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_RECEIVE_RESPONSE -Error description: DHA-CSP failed to receive a response from the DHA-Service. - -Error code: 32 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_QUERY_HEADERS -Error description: DHA-CSP failed to query headers when trying to get HTTP status code. - -Error code: 33 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_EMPTY_RESPONSE -Error description: DHA-CSP received an empty response from DHA-Service even though HTTP status was OK. - -Error code: 34 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_MISSING_RESPONSE -Error description: DHA-CSP received an empty response along with an HTTP error code from DHA-Service. - -Error code: 35 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_IMPERSONATE_USER -Error description: DHA-CSP failed to impersonate user. - -Error code: 36 | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_ACQUIRE_PDCNETWORKACTIVATOR -Error description: DHA-CSP failed to acquire the PDC activators that are needed for network communication when the device is in Connected standby mode. - -Error code: 0xFFFF | Error name: HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_UNKNOWN -Error description: DHA-CSP failed due to an unknown reason, this error is highly unlikely to occur. - -Error code: 400 | Error name: Bad_Request_From_Client -Error description: DHA-CSP has received a bad (malformed) attestation request. - -Error code: 404 | Error name: Endpoint_Not_Reachable -Error description: DHA-Service isn't reachable by DHA-CSP - ### DHA-Report V3 schema ```xml @@ -1455,6 +1400,287 @@ Error description: DHA-Service isn't reachable by DHA-CSP ``` +The following list of data points is verified by the DHA-Service in DHA-Report version 3. + +- **Issued**: The date and time DHA-report was evaluated or issued to MDM. + +- **AIKPresent**: When an Attestation Identity Key (AIK) is present on a device, it indicates that the device has an endorsement key (EK) certificate. It can be trusted more than a device that doesn't have an EK certificate. + + If AIKPresent = True (1), then allow access. + + If AIKPresent = False (0), then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI assets. + - Allow conditional access based on other data points that are present at evaluation time. For example, other attributes on the health certificate, or a device's past activities and trust history. + - Take one of the previous actions and additionally place the device in a watch list to monitor the device more closely for potential risks. + +- **ResetCount** (Reported only for devices that support TPM 2.0): This attribute reports the number of times a PC device has hibernated or resumed. + +- **RestartCount** (Reported only for devices that support TPM 2.0): This attribute reports the number of times a PC device has rebooted. + +- **DEPPolicy**: A device can be trusted more if the DEP Policy is enabled on the device. + + Data Execution Prevention (DEP) Policy defines a set of hardware and software technologies that perform extra checks on memory to help prevent malicious code from running on a system. Secure boot allows a limited list on x86/amd64 and on ARM NTOS locks it to on. + + DEPPolicy can be disabled or enabled by using the following commands in WMI or a PowerShell script: + + - To disable DEP, type **bcdedit.exe /set {current} nx AlwaysOff** + - To enable DEP, type **bcdedit.exe /set {current} nx AlwaysOn** + + If DEPPolicy = 1 (On), then allow access. + + If DEPPolicy = 0 (Off), then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI assets. + - Allow conditional access based on other data points that are present at evaluation time. For example, other attributes on the health certificate, or a device's past activities and trust history. + - Take one of the previous actions and additionally place the device in a watch list to monitor the device more closely for potential risks. + + DEP policy evaluation is a non binary status when queried. It is then mapped to an On/Off state. + + |DEP policy level |Description | Attestation reported level | Property value | + |--------------|-----------|------------|-------------| + |OptIn (default configuration) |Only Windows system components and services have DEP applied. | 0 | 2 | + |OptOut |DEP is enabled for all processes. Administrators can manually create a list of specific applications that do not have DEP applied. | 1 | 3 | + |AlwaysOn |DEP is enabled for all processess. | 3 | 1 | + |AlwaysOff |DEP is not enabled for any process. | 2 | 0 | + +- **BitLockerStatus** (Reports if BitLocker was enabled during initial boot.): + + When BitLocker is reported "on" at boot time, the device is able to protect data that is stored on the drive from unauthorized access, when the system is turned off or goes to hibernation. + + Windows BitLocker Drive Encryption, encrypts all data stored on the Windows operating system volume. BitLocker uses the TPM to help protect the Windows operating system and user data and helps to ensure that a computer isn't tampered with, even if it's left unattended, lost, or stolen. + + If the computer is equipped with a compatible TPM, BitLocker uses the TPM to lock the encryption keys that protect the data. As a result, the keys can't be accessed until the TPM has verified the state of the computer. + + If BitLockerStatus = 1 (On), then allow access. + + If BitLockerStatus = 0 (Off), then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI assets. + - Allow conditional access based on other data points that are present at evaluation time. For example, other attributes on the health certificate, or a device's past activities and trust history. + - Take one of the previous actions and additionally place the device in a watch list to monitor the device more closely for potential risks. + +- **BootManagerRevListVersion**: This attribute indicates the version of the Boot Manager that is running on the device, to allow you to track and manage the security of the boot sequence/environment. + + If BootManagerRevListVersion = [CurrentVersion], then allow access. + + If `BootManagerRevListVersion !`= [CurrentVersion], then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI and MBI assets. + - Place the device in a watch list to monitor the device more closely for potential risks. + - Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue. + +- **CodeIntegrityRevListVersion**: This attribute indicates the version of the code that is performing integrity checks during the boot sequence. Using this attribute can help you detect if the device is running the latest version of the code that performs integrity checks, or if it's exposed to security risks (revoked), and enforce an appropriate policy action. + + If CodeIntegrityRevListVersion = [CurrentVersion], then allow access. + + If `CodeIntegrityRevListVersion !`= [CurrentVersion], then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI and MBI assets. + - Place the device in a watch list to monitor the device more closely for potential risks. + - Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue. + +- **SecureBootEnabled**: When Secure Boot is enabled, the core components used to boot the machine must have correct cryptographic signatures that are trusted by the organization that manufactured the device. The UEFI firmware verifies this requirement before it lets the machine start. If any files have been tampered with, breaking their signature, the system won't boot. + + If SecureBootEnabled = 1 (True), then allow access. + + If SecurebootEnabled = 0 (False), then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI assets. + - Allow conditional access based on other data points that are present at evaluation time. For example, other attributes on the health certificate, or a device's past activities and trust history. + - Take one of the previous actions and additionally place the device in a watch list to monitor the device more closely for potential risks. + +- **BootDebuggingEnabled**: Boot debug-enabled points to a device that is used in development and testing. Devices that are used for test and development typically are less secure: the device may run unstable code, or be configured with fewer security restrictions that is required for testing and development. + + Boot debugging can be disabled or enabled by using the following commands in WMI or a PowerShell script: + + - To disable boot debugging, type **bcdedit.exe /set {current} bootdebug off**. + - To enable boot debugging, type **bcdedit.exe /set {current} bootdebug on**. + + If BootdebuggingEnabled = 0 (False), then allow access. + + If BootDebuggingEnabled = 1 (True), then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI assets. + - Place the device in a watch list to monitor the device more closely for potential risks. + - Trigger a corrective action, such as enabling VSM using WMI or a PowerShell script. + +- **OSKernelDebuggingEnabled**: OSKernelDebuggingEnabled points to a device that is used in development and testing. Devices that are used for test and development typically are less secure: they may run unstable code, or be configured with fewer security restrictions required for testing and development. + + If OSKernelDebuggingEnabled = 0 (False), then allow access. + + If OSKernelDebuggingEnabled = 1 (True), then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI assets. + - Place the device in a watch list to monitor the device more closely for potential risks. + - Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue. + +- **CodeIntegrityEnabled**: When code integrity is enabled, code execution is restricted to integrity verified code. + + Code integrity is a feature that validates the integrity of a driver or system file each time it's loaded into memory. Code integrity detects whether an unsigned driver or system file is being loaded into the kernel, or whether a system file has been modified by malicious software that is being run by a user account with administrator privileges. + + On x64-based versions of the operating system, kernel-mode drivers must be digitally signed. + + If CodeIntegrityEnabled = 1 (True), then allow access. + + If CodeIntegrityEnabled = 0 (False), then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI assets. + - Allow conditional access based on other data points that are present at evaluation time. For example, other attributes on the health certificate, or a device's past activities and trust history. + - Take one of the previous actions and additionally place the device in a watch list to monitor the device more closely for potential risks. + +- **TestSigningEnabled**: When test signing is enabled, the device doesn't enforce signature validation during boot, and allows the unsigned drivers (such as unsigned UEFI modules) to load during boot. + + Test signing can be disabled or enabled by using the following commands in WMI or a PowerShell script: + + - To disable boot debugging, type **bcdedit.exe /set {current} testsigning off**. + - To enable boot debugging, type **bcdedit.exe /set {current} testsigning on**. + + If TestSigningEnabled = 0 (False), then allow access. + + If TestSigningEnabled = 1 (True), then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI and MBI assets. + - Place the device in a watch list to monitor the device more closely for potential risks. + - Trigger a corrective action, such as enabling test signing using WMI or a PowerShell script. + +- **SafeMode**: Safe mode is a troubleshooting option for Windows that starts your computer in a limited state. Only the basic files and drivers necessary to run Windows are started. + + If SafeMode = 0 (False), then allow access. + + If SafeMode = 1 (True), then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI assets. + - Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue. + +- **WinPE**: Windows pre-installation Environment (Windows PE) is a minimal operating system with limited services that is used to prepare a computer for Windows installation, to copy disk images from a network file server, and to initiate Windows Setup. + + If WinPE = 0 (False), then allow access. + + If WinPE = 1 (True), then limit access to remote resources that are required for Windows OS installation. + +- **ELAMDriverLoaded** (Windows Defender): To use this reporting feature, you must disable "Hybrid Resume" on the device. Early launch anti-malware (ELAM) provides protection for the computers in your network when they start up and before third-party drivers initialize. + + In the current release, this attribute only monitors/reports if a Microsoft first-party ELAM (Windows Defender) was loaded during initial boot. + + If a device is expected to use a third-party antivirus program, ignore the reported state. + + If a device is expected to use Windows Defender and ELAMDriverLoaded = 1 (True), then allow access. + + If a device is expected to use Windows Defender and ELAMDriverLoaded = 0 (False), then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI assets. + - Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue. + +- **VSMEnabled**: Virtual Secure Mode (VSM) is a container that protects high value assets from a compromised kernel. VSM requires about 1 GB of memory – it has enough capability to run the LSA service that is used for all authentication brokering. + + VSM can be enabled by using the following command in WMI or a PowerShell script: + + `bcdedit.exe /set {current} vsmlaunchtype auto` + + If VSMEnabled = 1 (True), then allow access. + If VSMEnabled = 0 (False), then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Disallow access to HBI assets. + - Trigger a corrective action, such as informing the technical support team to contact the owner investigate the issue + +- **PCRHashAlgorithmID**: This attribute is an informational attribute that identifies the HASH algorithm that was used by TPM; no compliance action required. + +- **BootAppSVN**: This attribute identifies the security version number of the Boot Application that was loaded during initial boot on the attested device + + If reported BootAppSVN equals an accepted value, then allow access. + + If reported BootAppSVN doesn't equal an accepted value, then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Direct the device to an enterprise honeypot, to further monitor the device's activities. + +- **BootManagerSVN**: This attribute identifies the security version number of the Boot Manager that was loaded during initial boot on the attested device. + + If reported BootManagerSVN equals an accepted value, then allow access. + + If reported BootManagerSVN doesn't equal an accepted value, then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Direct the device to an enterprise honeypot, to further monitor the device's activities. + +- **TPMVersion**: This attribute identifies the version of the TPM that is running on the attested device. TPMVersion node provides to replies "1" and "2": + + - 1 means TPM specification version 1.2 + - 2 means TPM specification version 2.0 + + Based on the reply you receive from TPMVersion node: + + - If reported TPMVersion equals an accepted value, then allow access. + - If reported TPMVersion doesn't equal an accepted value, then take one of the following actions that align with your enterprise policies: + - Disallow all access + - Direct the device to an enterprise honeypot, to further monitor the device's activities. + +- **PCR0**: The measurement that is captured in PCR[0] typically represents a consistent view of the Host Platform between boot cycles. It contains a measurement of components that are provided by the host platform manufacturer. + + Enterprise managers can create an allowlist of trusted PCR[0] values, compare the PCR[0] value of the managed devices (the value that is verified and reported by HAS) with the allowlist, and then make a trust decision based on the result of the comparison. + + If your enterprise doesn't have an allowlist of accepted PCR[0] values, then take no action. + If PCR[0] equals an accepted allowlist value, then allow access. + + If PCR[0] doesn't equal any accepted listed value, then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Direct the device to an enterprise honeypot, to further monitor the device's activities. + +- **SBCPHash**: SBCPHash is the finger print of the Custom Secure Boot Configuration Policy (SBCP) that was loaded during boot in Windows devices, except PCs. + + If SBCPHash isn't present, or is an accepted allow-listed value, then allow access. + + If SBCPHash is present in DHA-Report, and isn't an allowlisted value, then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Place the device in a watch list to monitor the device more closely for potential risks. + +- **CIPolicy**: This attribute indicates the Code Integrity policy that is controlling the security of the boot environment. + + If CIPolicy isn't present, or is an accepted allow-listed value, then allow access. + + If CIPolicy is present and isn't an allow-listed value, then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Place the device in a watch list to monitor the device more closely for potential risks. + +- **BootRevListInfo**: This attribute identifies the Boot Revision List that was loaded during initial boot on the attested device. + + If reported BootRevListInfo version equals an accepted value, then allow access. + + If reported BootRevListInfo version doesn't equal an accepted value, then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Direct the device to an enterprise honeypot, to further monitor the device's activities. + +- **OSRevListInfo**: This attribute identifies the Operating System Revision List that was loaded during initial boot on the attested device. + + If reported OSRevListInfo version equals an accepted value, then allow access. + + If reported OSRevListInfo version doesn't equal an accepted value, then take one of the following actions that align with your enterprise policies: + + - Disallow all access. + - Direct the device to an enterprise honeypot, to further monitor the device's activities. + +- **HealthStatusMismatchFlags**: HealthStatusMismatchFlags attribute appears if DHA-Service detects an integrity issue (mismatch) in the DHA-Data it receives from device management solutions, for validation. + + If an issue is detected, a list of impacted DHA-report elements will be listed under the HealthStatusMismatchFlags attribute. + ### DHA-Report example ```xml @@ -1492,10 +1718,60 @@ xmlns="http://schemas.microsoft.com/windows/security/healthcertificate/validatio ``` +### HealthAttestation CSP status and error codes + +| Error Code | Error Name | Error Description | +|---|---|---| +| 0 | HEALTHATTESTATION_CERT_RETRIEVAL_UNINITIALIZED | This state is the initial state for devices that have never participated in a DHA-Session. | +| 1 | HEALTHATTESTATION_CERT_RETRIEVAL_REQUESTED | This state signifies that MDM client's Exec call on the node VerifyHealth has been triggered and now the OS is trying to retrieve DHA-EncBlob from DHA-Server. | +| 2 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED | This state signifies that the device failed to retrieve DHA-EncBlob from DHA-Server. | +| 3 | HEALTHATTESTATION_CERT_RETRIEVAL_COMPLETE | This state signifies that the device has successfully retrieved DHA-EncBlob from the DHA-Server. | +| 4 | HEALTHATTESTATION_CERT_RETRIEVAL_PCR_FAIL | Deprecated in Windows 10, version 1607. | +| 5 | HEALTHATTESTATION_CERT_RETRIEVAL_GETQUOTE_FAIL | DHA-CSP failed to get a claim quote. | +| 6 | HEALTHATTESTATION_CERT_RETRIEVAL_DEVICE_NOT_READY | DHA-CSP failed in opening a handle to Microsoft Platform Crypto Provider. | +| 7 | HEALTHATTESTATION_CERT_RETRIEVAL_WINDOWS_AIK_FAIL | DHA-CSP failed in retrieving Windows AIK | +| 8 | HEALTHATTESTATION_CERT_RETRIEVAL_FROM_WEB_FAIL | Deprecated in Windows 10, version 1607. | +| 9 | HEALTHATTESTATION_CERT_RETRIEVAL_INVALID_TPM_VERSION | Invalid TPM version (TPM version isn't 1.2 or 2.0) | +| 10 | HEALTHATTESTATION_CERT_RETRIEVAL_GETNONCE_FAIL | Nonce wasn't found in the registry. | +| 11 | HEALTHATTESTATION_CERT_RETRIEVAL_GETCORRELATIONID_FAIL | Correlation ID wasn't found in the registry. | +| 12 | HEALTHATTESTATION_CERT_RETRIEVAL_GETCERT_FAIL | Deprecated in Windows 10, version 1607. | +| 13 | HEALTHATTESTATION_CERT_RETRIEVAL_GETCLAIM_FAIL | Deprecated in Windows 10, version 1607. | +| 14 | HEALTHATTESTATION_CERT_RETRIEVAL_ENCODING_FAIL | Failure in Encoding functions. (Extremely unlikely scenario) | +| 15 | HEALTHATTESTATION_CERT_RETRIEVAL_ENDPOINTOVERRIDE_FAIL | Deprecated in Windows 10, version 1607. | +| 16 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_LOAD_XML | DHA-CSP failed to load the payload it received from DHA-Service. | +| 17 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_CORRUPT_XML | DHA-CSP received a corrupted response from DHA-Service. | +| 18 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_EMPTY | DHA-CSP received an empty response from DHA-Service. | +| 19 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_DECRYPT_AES_EK | DHA-CSP failed in decrypting the AES key from the EK challenge. | +| 20 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_DECRYPT_CERT_AES_EK | DHA-CSP failed in decrypting the health cert with the AES key. | +| 21 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_EXPORT_AIKPUB | DHA-CSP failed in exporting the AIK Public Key. | +| 22 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_CREATE_CLAIMAUTHORITYONLY | DHA-CSP failed in trying to create a claim with AIK attestation data. | +| 23 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_APPEND_AIKPUB | DHA-CSP failed in appending the AIK Pub to the request blob. | +| 24 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_APPEND_AIKCERT | DHA-CSP failed in appending the AIK Cert to the request blob. | +| 25 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_INIT_HTTPHANDLE | DHA-CSP failed to obtain a Session handle. | +| 26 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_GETTARGET_HTTPHANDLE | DHA-CSP failed to connect to the DHA-Service. | +| 27 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_CREATE_HTTPHAND | DHA-CSP failed to create an HTTP request handle. | +| 28 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_SET_INTERNETOPTION | DHA-CSP failed to set options. | +| 29 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_ADD_REQUESTHEADERS | DHA-CSP failed to add request headers. | +| 30 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_SEND_REQUEST | DHA-CSP failed to send the HTTP request. | +| 31 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_RECEIVE_RESPONSE | DHA-CSP failed to receive a response from the DHA-Service. | +| 32 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_QUERY_HEADERS | DHA-CSP failed to query headers when trying to get HTTP status code. | +| 33 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_EMPTY_RESPONSE | DHA-CSP received an empty response from DHA-Service even though HTTP status was OK. | +| 34 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_MISSING_RESPONSE | DHA-CSP received an empty response along with an HTTP error code from DHA-Service. | +| 35 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_IMPERSONATE_USER | DHA-CSP failed to impersonate user. | +| 36 | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_ACQUIRE_PDCNETWORKACTIVATOR | DHA-CSP failed to acquire the PDC activators that are needed for network communication when the device is in Connected standby mode. | +| 0xFFFF | HEALTHATTESTATION_CERT_RETRIEVAL_FAILED_UNKNOWN | DHA-CSP failed due to an unknown reason, this error is highly unlikely to occur. | +| 400 | Bad_Request_From_Client | DHA-CSP has received a bad (malformed) attestation request. | +| 404 | Endpoint_Not_Reachable | DHA-Service isn't reachable by DHA-CSP | + ## Security Considerations + DHA anchors its trust in the TPM and its measurements. If TPM measurements can be spoofed or tampered, DHA can't provide any guarantee of device health for that device. + For more information, see [PC Client TPM Certification](https://trustedcomputinggroup.org/resource/pc-client-tpm-certification/). + -## Related topics + -[Configuration service provider reference](index.yml) +## Related articles + +[Configuration service provider reference](configuration-service-provider-reference.md) diff --git a/windows/client-management/mdm/healthattestation-ddf.md b/windows/client-management/mdm/healthattestation-ddf.md index 74a707236c..3870db4bb5 100644 --- a/windows/client-management/mdm/healthattestation-ddf.md +++ b/windows/client-management/mdm/healthattestation-ddf.md @@ -1,458 +1,432 @@ --- -title: HealthAttestation DDF -description: Learn about the OMA DM device description framework (DDF) for the HealthAttestation configuration service provider. -ms.reviewer: +title: HealthAttestation DDF file +description: View the XML file containing the device description framework (DDF) for the HealthAttestation configuration service provider. +author: vinaypamnani-msft manager: aaroncz ms.author: vinpa -ms.topic: article +ms.date: 02/27/2023 +ms.localizationpriority: medium ms.prod: windows-client ms.technology: itpro-manage -author: vinaypamnani-msft -ms.date: 12/05/2017 +ms.topic: reference --- -# HealthAttestation DDF + +# HealthAttestation DDF file -This topic shows the OMA DM device description framework (DDF) for the **HealthAttestation** configuration service provider. DDF files are used only with OMA DM provisioning XML. - -Looking for the DDF XML files? See [CSP DDF files download](configuration-service-provider-ddf.md). - -The XML below is the current version for this CSP. +The following XML file contains the device description framework (DDF) for the HealthAttestation configuration service provider. ```xml - - - - - 1.2 - $(runtime.windows)\system32\hascsp.dll - - {9DCCCE22-C057-424E-B8D1-67935988B174} - - HealthAttestation - ./Vendor/MSFT - - - - - The root node for the device HealthAttestation configuration service provider. - - - - - - - - - - - com.microsoft/1.4/MDM/HealthAttestation - - - 10.0.10586 - 1.0 - - - - - - - - VerifyHealth - - - - - Notifies the device to prepare a device health verification request. - - - - - - - - - - - text/plain - - - - - - Status - - - - - Provides the current status of the device health request. For the complete list of status see https://learn.microsoft.com/windows/client-management/mdm/healthattestation-csp#device-healthattestation-csp-status-and-error-codes - - - - - - - - - - - text/plain - - - - - ForceRetrieve - - - - - - False - Instructs the client to initiate a new request to DHA-Service, and get a new DHA-EncBlob (a summary of the boot state that is issued by DHA-Service). This option should only be used if the MDM server enforces a certificate freshness policy, which needs to force a device to get a fresh encrypted blob from DHA-Service. - - - - - - - - - - - text/plain - - - - false - False - - - true - True - - - - - - Certificate - - - - - Instructs the DHA-CSP to forward DHA-Data to the MDM server. - - - - - - - - - - - text/plain - - - - - Nonce - - - - - - \0 - Enables MDMs to protect the device health attestation communications from man-in-the-middle type (MITM) attacks with a crypt-protected random value that is generated by the MDM Server. The nonce is in hex format, with a minimum size of 8 bytes, and a maximum size of 32 bytes. - - - - - - - - - - - text/plain - - - - - - - CorrelationID - - - - - Identifies a unique device health attestation session. CorrelationId is used to correlate DHA-Service logs with the MDM server events and Client event logs for debug and troubleshooting. - - - - - - - - - - - text/plain - - - - - - - HASEndpoint - - - - - - has.spserv.microsoft.com. - Identifies the fully qualified domain name (FQDN) of the DHA-Service that is assigned to perform attestation. If an FQDN is not assigned, DHA-Cloud (Microsoft owned and operated cloud service) will be used as the default attestation service. - - - - - - - - - - - text/plain - - - - - - - TpmReadyStatus - - - - - Returns a bitmask of information describing the state of TPM. It indicates whether the TPM of the device is in a ready and trusted state. - - - - - - - - - - - text/plain - - - 10.0.14393 - 1.1 - - - - - CurrentProtocolVersion - - - - - Provides the current protocol version that the client is using to communicate with the Health Attestation Service. - - - - - - - - - - - text/plain - - - 10.0.16299 - 1.3 - - - - - PreferredMaxProtocolVersion - - - - - - 3 - Provides the maximum preferred protocol version that the client is configured to communicate over. If this is higher than the protocol versions supported by the client it will use the highest protocol version available to it. - - - - - - - - - - - text/plain - - - 10.0.16299 - 1.3 - - - - - - - MaxSupportedProtocolVersion - - - - - Returns the maximum protocol version that this client can support. - - - - - - - - - - - text/plain - - - 10.0.16299 - 1.3 - - - - - TriggerAttestation - - - - - Notifies the device to trigger an attestation session asynchronously. - - - - - - - - - - - text/plain - - - 99.9.99999 - 1.4 - - - - - - - GetAttestReport - - - - - Retrieve attestation session report if exists. - - - - - - - - - - - - - - 99.9.99999 - 1.4 - - - - - AttestStatus - - - - - AttestStatus maintains the success or failure status code for the last attestation session. - - - - - - - - - - - text/plain - - - 99.9.99999 - 1.4 - - - - - GetServiceCorrelationIDs - - - - - Retrieve service correlation IDs if exist. - - - - - - - - - - - - - - 99.9.99999 - 1.4 - - - - - - - - - + +]> + + 1.2 + + + + HealthAttestation + ./Vendor/MSFT + + + + + The root node for the device HealthAttestation configuration service provider. + + + + + + + + + + + + + + 10.0.10586 + 1.0 + 0x4;0x1B;0x30;0x31;0x48;0x54;0x62;0x63;0x64;0x65;0x77;0x79;0x7A;0x7D;0x7E;0x81;0x82;0x88;0x8A;0x8B;0xA1;0xA2;0xA4;0xA5;0xAB;0xAC;0xAF;0xB4;0xBC;0xBF;0xCA;0xCB;0xCD; + + + + VerifyHealth + + + + + Notifies the device to prepare a device health verification request. + + + + + + + + + + + + + + + + Status + + + + + Provides the current status of the device health request. For the complete list of status see https://docs.microsoft.com/en-us/windows/client-management/mdm/healthattestation-csp#device-healthattestation-csp-status-and-error-codes + + + + + + + + + + + + + + + + ForceRetrieve + + + + + + False + Instructs the client to initiate a new request to DHA-Service, and get a new DHA-EncBlob (a summary of the boot state that is issued by DHA-Service). This option should only be used if the MDM server enforces a certificate freshness policy, which needs to force a device to get a fresh encrypted blob from DHA-Service. + + + + + + + + + + + + + + + false + False + + + true + True + + + + + + Certificate + + + + + Instructs the DHA-CSP to forward DHA-Data to the MDM server. + + + + + + + + + + + + + + + + Nonce + + + + + + \0 + Enables MDMs to protect the device health attestation communications from man-in-the-middle type (MITM) attacks with a crypt-protected random value that is generated by the MDM Server. The nonce is in hex format, with a minimum size of 8 bytes, and a maximum size of 32 bytes. + + + + + + + + + + + + + + + + + + CorrelationID + + + + + Identifies a unique device health attestation session. CorrelationId is used to correlate DHA-Service logs with the MDM server events and Client event logs for debug and troubleshooting. + + + + + + + + + + + + + + + + + + HASEndpoint + + + + + + has.spserv.microsoft.com. + Identifies the fully qualified domain name (FQDN) of the DHA-Service that is assigned to perform attestation. If an FQDN is not assigned, DHA-Cloud (Microsoft owned and operated cloud service) will be used as the default attestation service. + + + + + + + + + + + + + + + + + + TpmReadyStatus + + + + + Returns a bitmask of information describing the state of TPM. It indicates whether the TPM of the device is in a ready and trusted state. + + + + + + + + + + + + + + 10.0.14393 + 1.1 + + + + + CurrentProtocolVersion + + + + + Provides the current protocol version that the client is using to communicate with the Health Attestation Service. + + + + + + + + + + + + + + 10.0.16299 + 1.3 + + + + + PreferredMaxProtocolVersion + + + + + + 3 + Provides the maximum preferred protocol version that the client is configured to communicate over. If this is higher than the protocol versions supported by the client it will use the highest protocol version available to it. + + + + + + + + + + + + + + 10.0.16299 + 1.3 + + + + + + + MaxSupportedProtocolVersion + + + + + Returns the maximum protocol version that this client can support. + + + + + + + + + + + + + + 10.0.16299 + 1.3 + + + + + TriggerAttestation + + + + + Notifies the device to trigger an attestation session asynchronously. + + + + + + + + + + + + + + 10.0.22000 + 1.4 + + + + + GetAttestReport + + + + + Retrieve attestation session report if exists. + + + + + + + + + + + + + + 10.0.22000 + 1.4 + + + + + AttestStatus + + + + + AttestStatus maintains the success or failure status code for the last attestation session. + + + + + + + + + + + + + + 10.0.22000 + 1.4 + + + + + GetServiceCorrelationIDs + + + + + Retrieve service correlation IDs if exist. + + + + + + + + + + + + + + 10.0.22000 + 1.4 + + + + + ``` -## Related topics +## Related articles - -[HealthAttestation configuration service provider](healthattestation-csp.md) - -  - -  +[HealthAttestation configuration service provider reference](healthattestation-csp.md) diff --git a/windows/client-management/mdm/toc.yml b/windows/client-management/mdm/toc.yml index f664d78079..4e65bfcfd6 100644 --- a/windows/client-management/mdm/toc.yml +++ b/windows/client-management/mdm/toc.yml @@ -758,7 +758,7 @@ items: - name: HealthAttestation href: healthattestation-csp.md items: - - name: HealthAttestation DDF + - name: HealthAttestation DDF file href: healthattestation-ddf.md - name: LanguagePackManagement href: language-pack-management-csp.md