Supplicant API Call Sequence
This topic provides the specific call sequence for the supplicant API.
Supplicant API Call Sequence Overview
When the supplicant receives an EAP packet from a provider, such as an access point, the following supplicant API call flow typically occurs.
- The application calls EapHostPeerBeginSession with EAPHost configuration data and user data. A successful call returns an EAP_SESSION_HANDLE session handle.
- Each packet received by the supplicant is processed by a call to EapHostPeerProcessReceivedPacket. The supplicant then calls the function corresponding to the action code returned by the function.
- If the action code is EapHostPeerResponseSend, then the supplicant calls EapHostPeerGetSendPacket to obtain the response to be sent to the authenticator.
- If during the session, the action code returned to the supplicant is EapHostPeerResponseRespond, it indicates that EAP attributes are available. The supplicant then calls EapHostPeerGetResponseAttributes to obtain them. These attributes contain supplemental data used during the authentication process. After supplicant completes processing the attributes it calls EapHostPeerSetResponseAttributes which updates the data. This function returns an action code which determines the supplicant's next action.
- If the action code is EapHostPeerResponseInvokeUI the supplicant raises a user interface dialog to obtain interactive data from the user, such as credentials or identity information. See User Interaction with the Supplicant API Call Flow below.
- If the action code is EapHostPeerResponseResult, it indicates that the results of the authentication session are available to the supplicant. The supplicant then calls EapHostPeerGetResult to obtain the results. Regardless of whether the results indicate success or failure, the supplicant calls EapHostPeerEndSession. In the case of failure, re-authentication can be attempted by opening another session with EAPHost and providing a new identity, or attempting authentication with the original identity again.
User Interaction with the Supplicant API Call Flow
In certain cases, the supplicant needs to obtain information from the user to continue the authentication process.
The following list demonstrates the sequence of calls on the supplicant and EAPHost UI process necessary to enable interactive input.
The supplicant obtains the current user interface context by calling EapHostPeerGetUIContext.
The supplicant then sends the UI context data to the supplicant UI process.
Note
The UI process, which typically collects UI or handles interactive UI, is separate from the supplicant process. Separating the two processes is not a requirement of EAPHost, but doing so has the advantage of allowing the UI process to interact with the desktop.
If the supplicant wants to render the UI by itself then it calls the EapHostPeerQueryInteractiveUIInputFields function to obtain the input fields for interactive UI components to be raised. Otherwise, it follows the traditional model of invoking method interactive UI by calling EapHostPeerInvokeInteractiveUI
Note
If EAP_E_EAPHOST_METHOD_OPERATION_NOT_SUPPORTED is returned, the supplicant must follow the traditional model of invoking method interactive UI by calling EapHostPeerInvokeInteractiveUI. If there is an error, EapHostPeerQueryInteractiveUIInputFields will return a return code other than NULL.
Whether the supplicant calls EapHostPeerQueryInteractiveUIInputFields or EaphostPeerInvokeInteractiveUI the UI process passes the existing context data and loads Eappcfg.dll. Appropriate UI is raised to collect the new data. The new UI context data, which may now contain user input, is copied, and the old context data is released with a call to EapPeerFreeMemory.
The UI process returns the new context data to the supplicant, which calls EapHostPeerSetUIContext to set it.
Related topics