Share via

EapHostPeerBeginSession (Compact 7)

  • Article

3/12/2014

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 APIENTRY EapHostPeerBeginSession(
  __in   DWORD dwFlags,
  __in   EAP_METHOD_TYPE eapType,
  __in   const EapAttributes* pAttributeArray,
  __in   HANDLE hTokenImpersonateUser,
  __in   DWORD dwSizeOfConnectionData,
  __in   const BYTE* pConnectionData,
  __in   DWORD dwSizeOfUserData,
  __in   const BYTE* pUserData,
  __in   DWORD dwMaxSendPacketSize,
  __in   const GUID* pConnectionId,
  __in   NotificationHandler func,
  __in   VOID* pContextData,
  __out  EAP_SESSIONID* pSessionId,
  __out  EAP_ERROR** ppEapError
);

Parameters

  • dwFlags
    A combination of EAP Method Flags that describe the new EAP authentication session behavior.
  • eapType
    An EAP_METHOD_TYPE structure that specifies the type of EAP authentication to use for this session.
  • pAttributeArray
    Pointer to an EAP_ATTRIBUTES structure that specifies the EAP attributes of the entity to authenticate.
  • hTokenImpersonateUser
    Handle to the user impersonation token to use in this session.
  • dwSizeOfConnectionData
    The size, in bytes, of the connection data buffer provided in pConnectionData.
  • pConnectionData
    Describes the configuration used for authentication. NULL connection data is considered valid. The method should work with the default configuration.
  • dwSizeOfUserData
    The size, in bytes, of the user data buffer provided in pUserData.

  • 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 or a certificate store, for example.

    The EAP method author defines both the default credentials and alternate credentials.

  • dwMaxSendPacketSize
    The maximum size, in bytes, of an EAP packet that can be sent during the session.
  • 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.

  • 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);

  • 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.

    The following code shows a NotificationHandler callback call.

    func(*pConnectionId, pContextData);
  • pSessionId
    A pointer to an EAP_SESSIONID structure that contains the unique handle for this EAP authentication session on the EAPHost server.
  • 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.

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.

The call to EapHostPeerBeginSession to establish the re-authentication session can be made from the callback specified in the func parameter and called when the health state changes. This callback function indicates to the supplicant to tear down the network authentication associated with the GUID and re-authenticate.

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.

Note

Registering the connection refers to providing a valid GUID and valid callback function pointer.

See Also

Reference

EAPHost Supplicant Run-time Functions
EapHostPeerEndSession
EapHostPeerClearConnection