This section describes the internal operations of DFCI.
Communications with Provider¶
DFCI communicates with a controlling identity. One of the controlling identities could be Microsoft Intune. The communications path from the controlling identity is though the use of UEFI variables. DFCI processes the mailbox variables during a system restart.
In the source code, the Identity manager is implemented in IdentityAndAuthManager is defined in the DfciPkg located in the mu_plus repository https://github.com/microsoft/mu_plus/. Identity and Auth Manager is responsible for managing the Identities. The initial state of the system has the Local User with full authentication to make changes to any of the available settings. There are six Identities known by DFCI:
|Identity||Use of the Identity|
|Owner||The system owner. Used by a controlling agent - that authorizes Use to control some settings|
|User||A delegated user. Used by Microsoft Intune.|
|User1||Not currently used|
|User2||Not currently used|
|Local User||Not a certificate - just a known, default, user|
|Zero Touch||Limited use Identity to allow an Enroll from a controlling agent. The system has the Zero Touch Certificate installed during manufacturing. Zero Touch cannot be enrolled through the normal enroll operation. Zero Touch has no use when a system is enrolled.|
The Identity Manager reads the incoming mailbox to process a Identity enroll, Identity certificate update, and Identity unenroll operations. Except for the Local User, when an Identity is enrolled, it means adding a Certificate that will be used to validate incoming settings.
The Identity Manager verifies that the incoming identity mailbox packet:
- Is signed by one of the Identities
- The signed identity has permission to update the target identity.
- Target information in the packet matches the system information
The one exception is when an new Owner is being enrolled, no Identities validate the mailbox packet, and the Local User has permission to enroll an owner, DFCI will pause booting to prompt the Local User for permission to do the enroll. The user will be asked to validate the enrollment by entering the last two characters of the new owners certificate hash.
When installed by the manufacturer of the system, the Zero Touch certificate will have permission to allow the Zero Touch owner packet to be enrolled without user intervention. Hence, the term Zero Touch enrollment.
The permission manager processes incoming permission mailbox packets. Permission packets must be signed by one of Owner, User, User1 or User2. When processing the incoming permissions XML, the signer permissions are used to enable adding or changing a permission.
The settings manager processes incoming settings mailbox packets. Settings packets must be signed by one of Owner, User, User1 or User2. When processing the incoming settings XML, the signer permissions are used to change a setting.
Identity Packet Formats¶
An Identity packet consists of a binary header, a DER encoded certificate file, a test signature validating the signing capability, and the signature of the packet:
The Test Signature is the detached signature of signing the public key certificate by the private key of the public key certificate. The Signature field of the packet is the detached signature of signing Header-PublicCert-TestSignature by:
|Enroll||The private key of the matching Public Key Certificate|
|Roll||The private key matching the public cert of the Identity being rolled.|
|Unenroll||The private key matching the public cert of the Identity being unenrolled.|
Permission Packet Formats¶
A Permission packet consists of a binary header, an XML payload, and a signature:
Sample permission packet:
<?xml version="1.0" encoding="utf-8"?> <PermissionsPacket xmlns="urn:UefiSettings-Schema"> <CreatedBy>Cloud Controller</CreatedBy> <CreatedOn>2018-03-28</CreatedOn> <Version>1</Version> <LowestSupportedVersion>1</LowestSupportedVersion> <Permissions Default="129" Delegated="192" Append="False"> <!-- Sample DDS initial enroll permissions Permission Mask - 128 = Owner 64 = User 32 = User1 16 = User2 8 = ZTD 1 = Local User Owner keeps the following settings for itself --> <Permission> <Id>Dfci.OwnerKey.Enum</Id> <PMask>128</PMask> <DMask>128</DMask> </Permission> <Permission> <Id>Dfci.Recovery.Enable</Id> <PMask>128</PMask> <DMask>128</DMask> </Permission> <Permission> <!-- Needs 128 (Owner Permission) to set the key, Needs 64 (User Permission) for User to roll the key --> <Id>Dfci.UserKey.Enum</Id> <PMask>192</PMask> <DMask>128</DMask> </Permission> <Permission> <Id>Dfci.RecoveryBootstrapUrl.String</Id> <PMask>128</PMask> <DMask>128</DMask> </Permission> <Permission> <Id>Dfci.RecoveryUrl.String</Id> <PMask>128</PMask> <DMask>128</DMask> </Permission> <Permission> <Id>Dfci.Hwid.String</Id> <PMask>128</PMask> <DMask>128</DMask> </Permission> </Permissions> </PermissionsPacket>
Settings Packet Formats¶
Sample settings payload:
<?xml version="1.0" encoding="utf-8"?> <SettingsPacket xmlns="urn:UefiSettings-Schema"> <CreatedBy>Mike Turner</CreatedBy> <CreatedOn>2019-03-06 10:10:00</CreatedOn> <Version>2</Version> <!-- Make sure you edit DfciSettingsPattern.xml and then run BuildSettings.bat to generate the DfciSettings.xml --> <LowestSupportedVersion>2</LowestSupportedVersion> <Settings> <Setting> <Id>Dfci.RecoveryBootstrapUrl.String</Id> <Value>http://some URL to access recovery cert updates/</Value> </Setting> <Setting> <Id>Dfci.RecoveryUrl.String</Id> <Value>https://some URL to access recovery update packets/</Value> </Setting> <Setting> <Id>Dfci.HttpsCert.Binary</Id> <Value> <!-- This is where a BASE64 encoded string of the certificate used for HTTPS operations is stored. --> wA== </Value> </Setting> <Setting> <Id>Dfci.RegistrationId.String</Id> <Value> 12345678-1234-5678-1234-012345674321 </Value> </Setting> <Setting> <Id>Dfci.TenantId.String</Id> <Value> 98765432-1234-5678-1234-012345674321 </Value> </Setting> </Settings> </SettingsPacket>
In order to minimize rebooting when accepting packets from the owner, there are 6 mailboxes for DFCI There are two for each Identity, Permission, and Settings. We call them:
Only packets of the correct type are processed out of each mailbox. Packets are processed in the following order:
- Enroll Identity
- Enroll Identity2
- Apply Permission
At this point, if there is a severe error, the Identities and Permissions are reverted to what they were before processing the packets. The following are still processed, in order.
- Unenroll Identity 2
- Unenroll Identity
Intune accesses the variables through the UEFI CSP provider.
Out of band recovery¶
Normally, the cloud provider would just send unenroll packets through the OS to the UEFICsp. However, if Windows is unable to boot, the UEFI front page application has a method to contact the owner via HTTPS.
Settings providers provide an interface for DFCI to access platform settings. The OEM is responsible for providing one or more settings providers for platform settings. The OEM is required to implement an instance of DfciGroupLib that maps DFCI-standard settings to OEM platform settings. While DFCI-standard settings are abstract (eg. Dfci.OnboardAudio.Enable), a platform may have multiple settings that cover portions of audio. For example, there may be a microphone or other input setting, and a setting to enable or disable the audio output. Using the DfciGroup lib, the individual platform settings can be mapped to the DFCI-standard settings. For more information on groups, see Dfci Groups
Setting Provider expected return codes:¶
|Return Code||Reason to return this code|
|EFI_SUCCESS||Operation of get or set was successful, and the returned value, if any, is valid|
|EFI_NOT_FOUND||Returned by DFCI if a setting provider is not found. See notes|
|EFI_UNSUPPORTED||Particular operation is not supported. See notes|
|EFI_BUFFER_TOO_SMALL||Get operation called with 0 size to get the size of a buffer to allocate|
|EFI_INVALID_PARAMETER||Coding error that provided incorrect parameters|
|EFI_OUT_OF_RESOURCES||Possibly out of memory, or some other lower function error|
Notes on EFI_NOT_FOUND¶
There are two expected reasons a settings provider could return EFI_NOT_FOUND. The first is that the settings is a DFCI standard setting from a newer version of DFCI than was implemented in the platform. The second is that the setting does not apply to the platform because it does not contain the feature. For example, if a platform has no cameras at all, it should not implement a Settings Provider for them. When EFI_NOT_FOUND is returned, Intune will additionally compare the DFCI version reported to determine compliance. For example, a platform reporting DFCI v1, and which has no cameras, returns EFI_NOT_FOUND on a request to disable all cameras. Intune infers that the lack of a standard settings provider for a given version of DFCI indicates that a setting is not relevant. On attempts to enable or disable this setting, Intune remaps this error reporting compliant or not-applicable. On a request to disable WPBT (a DFCI version 2 feature), the same platform would return EFI_NOT_FOUND because it lacks a DFCI version 2 Standard WPBT settings provider. Intune would observe the DFCI version, and report non-compliant, because the platform cannot manage or reliably report the status of the requested setting.
Notes on EFI_UNSUPPORTED¶
There are reasons for an operation to be not supported. One example is that a platform may provide a setting provider that has a setting that is always disabled, and return EFI_UNSUPPORTED when there is an attempt to enable that setting. Another case is if the hardware doesn't support the setting, or the OEM has chosen not to allow certain settings.
Settings provider for enabled features without platform control¶
Please refer to the DfciVirtualizationSettings provider in Project mu_plus for this section. A platform may conform to a Enabled setting, but have no method to control this setting. The CPU and I/O virtualization setting is one of those. The table below indicates the return code for specific cases of of this type of provider:
|Return Code||Reason to return this code|
|EFI_SUCCESS||Operation of get was successful, and the returned value is valid|
|EFI_UNSUPPORTED||A Set operation is not allowed|
Copyright (C) Microsoft Corporation. All rights reserved.