EapHostPeerBeginSession 函数 (eappapis.h)

项目
08/23/2023

启动 EAP 身份验证会话。如果 EapHostPeerBeginSession 函数成功，调用方还必须调用 EapHostPeerEndSession 以结束身份验证会话。无论 EapHostPeerBeginSession 以外的函数是成功还是失败，都必须调用后一个函数。

如果需要重新身份验证，无论原因如何，参数 pConnectionId 表示的接口都将取消注册。在取消注册 pConnectionId 的情况下，还必须调用 EapHostPeerClearConnection 来删除连接。

在未调用 EapHostPeerEndSession 的情况下，切勿在接口上再次调用 EapHostPeerBeginSession。 pConnectionId 指定的接口上只能有一个身份验证会话处于活动状态。

语法

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

参数

[in] dwFlags

描述新 EAP 身份验证会话行为的 EAP 标志的组合。

[in] eapType

一个EAP_METHOD_TYPE结构，指定要用于此会话的 EAP 身份验证的类型。

[in] pAttributeArray

指向 EapAttributes 结构的指针，该结构指定要进行身份验证的实体的 EAP 属性。

[in] hTokenImpersonateUser

要在此会话中使用的用户模拟令牌的句柄。

[in] dwSizeofConnectionData

pConnectionData 中提供的连接数据缓冲区的大小（以字节为单位）。

[in] pConnectionData

描述用于身份验证的配置。 NULL 连接数据被视为有效。方法应适用于默认配置。

[in] dwSizeofUserData

pUserData 中提供的用户数据缓冲区的大小（以字节为单位）。

[in] pUserData

指向字节缓冲区的指针，该缓冲区包含从 EapPeerGetIdentity 函数返回的用户数据的不透明用户数据 BLOB。用户数据可能包括用于身份验证的凭据或证书。 pUserData 可以为 NULL。 NULL 指针的解释取决于方法的实现。用户数据由用于身份验证的用户或计算机凭据组成。通常，用户数据取决于配置数据。

如果在 dwflags 中指示EAP_FLAG_PREFER_ALT_CREDENTIALS，则传递到 EapPeerBeginSession 的凭据优先于所有其他形式的凭据检索，即使传入 pConnectionData 的配置数据请求不同的凭据检索模式也是如此。如果将凭据传递到 EapPeerBeginSession 失败，则 EAPHost 将采用方法特定的凭据检索，在这种情况下，可以从文件、Windows 登录名或证书存储等获取凭据。

EAP 方法作者定义默认凭据和备用凭据。例如，在 EAP-MSCHAPv2 默认凭据是从 winlogon 获取的 Windows 凭据，备用凭据是传递到 pUserData (用户名、密码、域) 凭据。

[in] dwMaxSendPacketSize

可在会话期间发送的 EAP 数据包的最大大小（以字节为单位）。

[in] pConnectionId

指向 GUID 值的指针，该值唯一标识将对其执行请求者身份验证的逻辑网络接口。如果请求者在 NAP 运行状况更改后寻求重新身份验证，它应提供唯一的 GUID。当隧道方法调用此函数以启动其内部方法时，参数应为 NULL 。当 pConnectionId 参数为 NULL 时， 将忽略 func 和 pContextData 参数。

[in] func

一个 NotificationHandler 函数指针，提供 EAPHost 在需要重新身份验证时通知请求方使用的回调。

如果函数处理程序为 NULL，则忽略 pContextData 参数。如果函数处理程序为 NULL，则还意味着调用方对 EAP 隔离强制客户端 (QEC) 的 SoH 更改通知不感兴趣。

以下代码显示了 NotificationHandler 回调调用。

func(*pConnectionId, pContextData);

[in] pContextData

一个指针，用于重新身份验证上下文数据，请求者将在调用 func 时将其与连接关联。此参数可以为 NULL。

[out] pSessionId

指向 EAP_SESSIONID 结构的指针，该结构包含 EAPHost 服务器上的此 EAP 身份验证会话的唯一句柄。

[out] ppEapError

指向 EAP_ERROR 结构的地址的指针。在调用此函数之前，地址应设置为 NULL 。如果错误数据可用，则会收到指向 EAP_ERROR 结构的地址的指针，该结构包含执行此函数调用期间引发的任何错误。使用错误数据后，通过调用 EapHostPeerFreeEapError 释放此内存。

返回值

无

备注

如果 EAPHost 请求者正在参与 NAP，则请求方将响应其网络运行状况状态的更改。如果该状态发生更改，则请求方必须启动重新身份验证会话，如下所示。

如果在重新进行身份验证时存在当前会话，则请求者应通过调用 EapHostPeerEndSession 来断开当前会话，然后通过调用 EapHostPeerBeginSession 来启动新会话。
如果没有重新身份验证的当前会话，或者上一个会话已通过调用 EapHostPeerEndSession 结束，则请求者只需通过调用 EapHostPeerBeginSession 来启动新会话。

可以通过 func 参数中指定的回调调用 EapHostPeerBeginSession 来建立重新身份验证会话，并在运行状况状态更改时调用。此回调函数指示请求者断开与 GUID 关联的网络身份验证并重新进行身份验证。

可以在多个会话之间保持连接，因为 EapHostPeerBeginSession 可以提供有效的 GUID 来注册连接。调用 EapHostPeerEndSession 时，仅终止当前会话。由于使用 GUID 的注册不会终止， 因此 EapHostPeerBeginSession 的原始注册保持不变。因此，注册在多个会话中有效。

注意注册连接是指提供有效的 GUID 和有效的回调函数指针。

要求


最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	eappapis.h
Library	Eappprxy.lib
DLL	Eappprxy.dll

请参阅

EAPHost 请求运行时函数

EapHostPeerClearConnection

EapHostPeerEndSession

SSO 和 PLAP

通过

EapHostPeerBeginSession 函数 (eappapis.h)

语法

参数

返回值

备注

要求

请参阅

反馈

其他资源