This topic provides answers to commonly-asked questions about the EAPHost Supplicant API.
Why do I need to call "EapHostPeerInitialize" and "EapHostPeerUninitialize"?
EapHostPeerInitialize and EapHostPeerUninitialize initialize and uninitialize the COM environment used for interprocess communication (IPC) between a supplicant and EAPHost.
Which functions must be invoked on threads that have COM initialized for Single Threaded Apartment (STA)?
EapHostPeerInvokeConfigUI, EapHostPeerInvokeInteractiveUI, and EapHostAuthenticatorInvokeConfigUI must be called on threads that have COM initialized for STA. This can be achieved by calling COM API CoInitialize; when the supplicant has finished with the STA thread CoUninitialize must be called before exiting.
How does EAPHost export keying material?
EAPHost EAP methods export Master Session Keys (MSKs)in the form of Microsoft Point-to-Point Encryption (MPPE) keys to the supplicants. Additional keying material, such as Pairwise Master Keys (PMKs) can be generated by the supplicant using the MSK. For the methods to generate any other keys during authentication, the methods can provide those keys as vendor-specific attributes to the supplicants.
What is an Extended Master Session Key (EMSK)?
EMSK is additional keying material that is exported by the EAP method. EMSK is at least 64 octets in length. EMSK is shared between the EAP client and server, but is not shared with the authenticator or any other third party. Currently, EMSK is reserved for future use. For more information, see Extensible Authentication Protocol EAP) Method Requirements for Wireless LANs.
When does a method consume or generate an attribute?
If an EAP method generates attributes or EMSK, then the supplicant will consume attributes. Typically, attributes that are consumed by supplicants are keys. The attributes consumed are eatPeerId, eatServerId, eatMethodId, eatEMSK, and eatCredentialsChanged. For more information, see EAP_ATTRIBUTE_TYPE. An EAP method can export additional application-specific EMSK material such as:
- Session ID
- [Network Access Protection](/windows/desktop/NAP/network-access-protection-start-page) (NAP)
Which attributes does 802.1X consume?
The native wireless 802.1X supplicant will consume the following EAPHost authentication attributes:
- Change password notification
- Microsoft Point-to-Point Encryption (MPPE) send/receive keys. VendorId/VendorType = 331/16 and 311/1
MPPE keys are keys generated at the end of successful authentication, by both peer and authenticator. These keys are used by 802.1X and the network access server (NAS) to encrypt and decrypt packets that are sent and received.
What's the purpose of the EAP_PEER_FLAG_GUEST_ACCESS flag in EAPHost?
When this flag is set in EAPHostPeerBeginSession, EAPHost interprets this as a request for guest authorization and returns a NULL identity response that is then passed to the supplicant and returned to the EAP Server.
How does the supplicant request machine authentication?
Machine authentication is requested by setting the EAP_FLAG_MACHINE_AUTH flag.
How does the supplicant request user authentication?
User authentication is requested by not setting the EAP_FLAG_MACHINE_AUTH flag.
When do I use "EapHostPeerFreeErrorMemory" instead of the "EapHostFreeEapError" function?
The EapHostPeerFreeErrorMemory function is used only for freeing EAP_ERROR structures returned by EAPHost configuration APIs. EAPHost configuration APIs are defined in EapHostPeerConfigApis.h. In contrast, the EapHostPeerFreeEapError function is used for freeing EAP_ERROR structures returned by EAPHost run-time APIs. EAPHost run-time APIs are defined in EapPApis.h. Never use the run-time version of the API with the configuration version of the APIs; to do so could produce unexpected results.
I have implemented my UI in the same thread that I use to process an EAP authentication session on the supplicant. After I have raised an interactive user interface dialog box to obtain credentials or other user input data, the next call by the EAPHost to an EAP peer method fails with "ERROR_OBJECT_DISCONNECTED". Why has this occurred, and how do I address it?
While the EAPHost client-side APIs are all C style APIs, these C APIs are just wrappers of corresponding COM APIs. The C style APIs run in a multithreaded COM environment. UI code usually runs in the apartment thread model. Because the two thread models conflict with one another, do not run the UI code in the same thread that processes EAP authentications.
Why does the "EapHostPeerBeginSession" API take a "NotificationHandler" callback function pointer as a parameter?
NotificationHandler is the mechanism by which a supplicant is notified that it must re-authenticate. There are various scenarios where the supplicant is required to re-authenticate, including authentication with Network Access Protection (NAP).
What is the purpose of the "pConnectionId" parameter in the "EapHostPeerBeginSession" API?
pConnectionId is a pointer to a supplicant-defined GUID value used to identify a network connection that belongs to the supplicant. When the NotificationHandler callback function is called, this GUID is passed to identify the network connection that the supplicant will use for re-authentication requests.
How do I know if there is a change in quarantine state?
The user will receive visual notification of a change in quarantine state only if there is at least one Network Access Protection (NAP) quarantine enforcement client (QEC) registered interface in the system. If so, when re-authentication is attempted the user will be notified of a quarantine state change via a pop-up window.
How do I know if there is a NAP QEC registered interface in the system?
Open an elevated window, and run the following netsh command: "netsh nap client show state". For more information, see Netsh Commands.
If the supplicant re-authenticates, what connection ID should the QEC use during re-authentication?
The QEC should use the same connection ID that was used for the previous session.
There is only one EAPHost supplicant method available to display user interface (UI) dialog boxes, but EAP methods have several types of UI-specific calls. What method should the supplicant call when it obtains the "EapHostPeerResponseInvokeUI" action code, indicating that the supplicant must display a UI dialog box?
No action is required by the user because EAPHost knows which method function to call. For instance, when action code EapHostPeerResponseInvokeUI is returned, the supplicant calls these three functions in the following order: EapHostPeerGetUIContext, EapHostPeerInvokeInteractiveUI, and EapHostPeerSetUIContext.
What is the difference between a credentials BLOB and a configuration BLOB?
The credentials BLOB contains only user data such as user name, password, and PIN. The configuration BLOB contains the settings that control the behavior of the method.
Can I enable tracing on the EAPHost client side?
Yes. For more information, see Enabling Tracing.