EapHostPeerBeginSession function (eappapis.h)
Starts an EAP authentication session. If the EapHostPeerBeginSession function succeeds, the caller must also call EapHostPeerEndSession to end the authentication session. The latter function must be called regardless of whether functions other than EapHostPeerBeginSession succeed or fail.
If re-authentication is required, regardless of the reason, the interface represented by the parameter pConnectionId will be unregistered. In cases where pConnectionId is unregistered, you must also call EapHostPeerClearConnection to remove the connection.
Never call EapHostPeerBeginSession again on an interface without calling EapHostPeerEndSession. Only one authentication session can be active on the interface specified by pConnectionId.
Syntax
DWORD EapHostPeerBeginSession(
[in] DWORD dwFlags,
[in] EAP_METHOD_TYPE eapType,
[in] const EapAttributes * const pAttributeArray,
[in] HANDLE hTokenImpersonateUser,
[in] DWORD dwSizeofConnectionData,
[in] const BYTE * const pConnectionData,
[in] DWORD dwSizeofUserData,
[in] const BYTE * const pUserData,
[in] DWORD dwMaxSendPacketSize,
[in] const GUID * const pConnectionId,
[in] NotificationHandler func,
[in] void *pContextData,
[out] EAP_SESSIONID *pSessionId,
[out] EAP_ERROR **ppEapError
);
Parameters
[in] dwFlags
A combination of EAP flags that describe the new EAP authentication session behavior.
[in] eapType
An EAP_METHOD_TYPE structure that specifies the type of EAP authentication to use for this session.
[in] pAttributeArray
Pointer to an EapAttributes structure that specifies the EAP attributes of the entity to authenticate.
[in] hTokenImpersonateUser
Handle to the user impersonation token to use in this session.
[in] dwSizeofConnectionData
The size, in bytes, of the connection data buffer provided in pConnectionData.
[in] pConnectionData
Describes the configuration used for authentication. NULL connection data is considered valid. The method should work with the default configuration.
[in] dwSizeofUserData
The size, in bytes, of the user data buffer provided in pUserData.
[in] pUserData
A pointer to a byte buffer that contains the opaque user data BLOB containing user data returned from the EapPeerGetIdentity function. User data may include credentials or certificates used for authentication. pUserData can be NULL. The interpretation of a NULL pointer depends on the implementation of a method. The user data consists of user or machine credentials used for authentication. Typically the user data depends on the configuration data.
If EAP_FLAG_PREFER_ALT_CREDENTIALS is indicated in dwflags, then credentials passed into EapPeerBeginSession are preferred to all other forms of credential retrieval, even if configuration data passed into pConnectionData requests a different mode of credential retrieval. If passing credentials into EapPeerBeginSession fails, then EAPHost resorts to method specific credential retrieval, in which case credentials could be obtained from a file, Windows login, or a certificate store, for example.
The EAP method author defines both the default credentials and alternate credentials. For example, in the case of EAP-MSCHAPv2 the default credentials are Windows credentials obtained from winlogon, and alternate credentials are the credentials (user name, password, domain) passed into pUserData.
[in] dwMaxSendPacketSize
The maximum size, in bytes, of an EAP packet that can be sent during the session.
[in] pConnectionId
A pointer to a GUID value that uniquely identifies the logical network interface over which the authentication of the supplicant will take place. If the supplicant seeks re-authentication after a NAP health change, it should provide a unique GUID. The parameter should be NULL when this function is called by a tunneling method to start its inner method. When the pConnectionId parameter is NULL, the func and pContextData parameters are ignored.
[in] func
A NotificationHandler function pointer that provides the callback used by EAPHost to notify the supplicant when re-authentication is needed.
If the function handler is NULL, the pContextData parameter is ignored. If the function handler is NULL, it also means that the caller is not interested in SoH change notification from the EAP quarantine enforcement client (QEC).
The following code shows a NotificationHandler callback call.
func(*pConnectionId, pContextData);
[in] pContextData
A pointer to re-authentication context data that the supplicant will associate with the connection when func is called. This parameter can be NULL.
[out] pSessionId
A pointer to an EAP_SESSIONID structure that contains the unique handle for this EAP authentication session on the EAPHost server.
[out] ppEapError
A pointer to the address of an EAP_ERROR structure. The address should be set to NULL before calling this function. If error data is available, a pointer to the address of an EAP_ERROR structure that contains any errors raised during the execution of this function call is received. After using the error data, free this memory by calling EapHostPeerFreeEapError.
Return value
None
Remarks
If an EAPHost supplicant is participating in NAP, the supplicant will respond to changes in the state of its network health. If that state changes, the supplicant must then initiate a re-authentication session as follows.
- If there is a current session when re-authentication occurs, the supplicant should tear down the current session by calling EapHostPeerEndSession, and then start a new session by calling EapHostPeerBeginSession.
- If there is no current session with re-authentication occurs, or the previous session was already ended by calling EapHostPeerEndSession, the supplicant only needs to start a new session by calling EapHostPeerBeginSession.
A connection can be kept across multiple sessions because EapHostPeerBeginSession can provide a valid GUID to register the connection. When EapHostPeerEndSession is called, only the current session is terminated. Because the registration with the GUID isn't terminated, the original registration by EapHostPeerBeginSession remains intact. Therefore, the registration is effective across multiple sessions.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | eappapis.h |
| Library | Eappprxy.lib |
| DLL | Eappprxy.dll |