EapHostPeerBeginSession-Funktion (eappapis.h)

Startet eine EAP-Authentifizierungssitzung. Wenn die EapHostPeerBeginSession-Funktion erfolgreich ist, muss der Aufrufer auch EapHostPeerEndSession aufrufen, um die Authentifizierungssitzung zu beenden. Die letztere Funktion muss aufgerufen werden, unabhängig davon, ob andere Funktionen als EapHostPeerBeginSession erfolgreich sind oder fehlschlagen.

Wenn eine erneute Authentifizierung erforderlich ist, wird die Registrierung der durch den Parameter pConnectionId dargestellten Schnittstelle aufgehoben. In Fällen, in denen pConnectionId nicht registriert ist, müssen Sie auch EapHostPeerClearConnection aufrufen, um die Verbindung zu entfernen.

Rufen Sie EapHostPeerBeginSession nie wieder auf einer Schnittstelle auf, ohne EapHostPeerEndSession aufzurufen. Nur eine Authentifizierungssitzung kann auf der von pConnectionId angegebenen Schnittstelle aktiv sein.

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

Parameter

[in] dwFlags

Eine Kombination von EAP-Flags , die das neue EAP-Authentifizierungssitzungsverhalten beschreiben.

[in] eapType

Eine EAP_METHOD_TYPE-Struktur , die den Typ der EAP-Authentifizierung angibt, die für diese Sitzung verwendet werden soll.

[in] pAttributeArray

Zeiger auf eine EapAttributes-Struktur , die die EAP-Attribute der zu authentifizierden Entität angibt.

[in] hTokenImpersonateUser

Behandeln Sie das Benutzeridentitätstoken, das in dieser Sitzung verwendet werden soll.

[in] dwSizeofConnectionData

Die Größe des in pConnectionData bereitgestellten Verbindungsdatenpuffers in Bytes.

[in] pConnectionData

Beschreibt die konfiguration, die für die Authentifizierung verwendet wird. NULL-Verbindungsdaten gelten als gültig. Die Methode sollte mit der Standardkonfiguration funktionieren.

[in] dwSizeofUserData

Die Größe des in pUserData bereitgestellten Benutzerdatenpuffers in Bytes.

[in] pUserData

Ein Zeiger auf einen Bytepuffer, der das undurchsichtige Benutzerdaten-BLOB enthält, das Benutzerdaten enthält, die von der EapPeerGetIdentity-Funktion zurückgegeben wurden. Benutzerdaten können Anmeldeinformationen oder Zertifikate enthalten, die für die Authentifizierung verwendet werden. pUserData kann NULL sein. Die Interpretation eines NULL-Zeigers hängt von der Implementierung einer Methode ab. Die Benutzerdaten bestehen aus Benutzer- oder Computeranmeldeinformationen, die für die Authentifizierung verwendet werden. In der Regel hängen die Benutzerdaten von den Konfigurationsdaten ab.

Wenn EAP_FLAG_PREFER_ALT_CREDENTIALS in dwflags angegeben ist, werden anmeldeinformationen, die an EapPeerBeginSession übergeben werden, allen anderen Formen des Abrufens von Anmeldeinformationen vorgezogen, auch wenn Konfigurationsdaten, die an pConnectionData übergeben werden, einen anderen Modus des Abrufens von Anmeldeinformationen anfordert. Wenn die Übergabe von Anmeldeinformationen an EapPeerBeginSession fehlschlägt, greift EAPHost auf den methodenspezifischen Abruf von Anmeldeinformationen zurück. In diesem Fall könnten Anmeldeinformationen z. B. aus einer Datei, einer Windows-Anmeldung oder einem Zertifikatspeicher abgerufen werden.

Der Autor der EAP-Methode definiert sowohl die Standardanmeldeinformationen als auch alternative Anmeldeinformationen. Im Fall von EAP-MSCHAPv2 sind die Standardanmeldeinformationen Windows-Anmeldeinformationen, die von winlogon abgerufen wurden, und alternative Anmeldeinformationen sind die Anmeldeinformationen (Benutzername, Kennwort, Domäne), die an pUserData übergeben werden.

[in] dwMaxSendPacketSize

Die maximale Größe eines EAP-Pakets in Bytes, das während der Sitzung gesendet werden kann.

[in] pConnectionId

Ein Zeiger auf einen GUID-Wert, der die logische Netzwerkschnittstelle eindeutig identifiziert, über die die Authentifizierung des Bittstellers erfolgt. Wenn der Bittsteller nach einer NAP-Integritätsänderung eine erneute Authentifizierung anstrebt, sollte er eine eindeutige GUID bereitstellen. Der Parameter sollte NULL sein, wenn diese Funktion von einer Tunnelmethode aufgerufen wird, um ihre innere Methode zu starten. Wenn der pConnectionId-ParameterNULL ist, werden die Parameter func und pContextData ignoriert.

[in] func

Ein NotificationHandler-Funktionszeiger , der den Rückruf bereitstellt, der von EAPHost verwendet wird, um das Supplicant zu benachrichtigen, wenn eine erneute Authentifizierung erforderlich ist.

Wenn der Funktionshandler NULL ist, wird der pContextData-Parameter ignoriert. Wenn der Funktionshandler NULL ist, bedeutet dies auch, dass der Aufrufer nicht an soH-Änderungsbenachrichtigungen vom EAP-Quarantäneerzwingungsclient (QEC) interessiert ist.

Der folgende Code zeigt einen NotificationHandler-Rückrufaufruf .

func(*pConnectionId, pContextData);

[in] pContextData

Ein Zeiger auf die erneute Authentifizierung von Kontextdaten, die der Supplicant der Verbindung zuordnen wird, wenn funkc aufgerufen wird. Dieser Parameter kann NULL sein.

[out] pSessionId

Ein Zeiger auf eine EAP_SESSIONID-Struktur , die das eindeutige Handle für diese EAP-Authentifizierungssitzung auf dem EAPHost-Server enthält.

[out] ppEapError

Ein Zeiger auf die Adresse einer EAP_ERROR-Struktur . Die Adresse sollte vor dem Aufrufen dieser Funktion auf NULL festgelegt werden. Wenn Fehlerdaten verfügbar sind, wird ein Zeiger auf die Adresse einer EAP_ERROR-Struktur empfangen, die alle Fehler enthält, die während der Ausführung dieses Funktionsaufrufs ausgelöst wurden. Nachdem Sie die Fehlerdaten verwendet haben, geben Sie diesen Arbeitsspeicher frei, indem Sie EapHostPeerFreeEapError aufrufen.

Rückgabewert

Keine

Bemerkungen

Wenn ein EAPHost-Supplicant an NAP teilnimmt, reagiert der Bittsteller auf Änderungen im Zustand seiner Netzwerkintegrität. Wenn sich dieser Zustand ändert, muss der Supplicant dann eine erneute Authentifizierungssitzung wie folgt initiieren.

• Wenn bei erneuter Authentifizierung eine aktuelle Sitzung vorhanden ist, sollte der Supplicant die aktuelle Sitzung durch Aufrufen von EapHostPeerEndSession abreißen und dann eine neue Sitzung starten, indem EapHostPeerBeginSession aufgerufen wird.
• Wenn keine aktuelle Sitzung mit erneuter Authentifizierung stattfindet oder die vorherige Sitzung bereits durch aufrufen von EapHostPeerEndSession beendet wurde, muss der Supplicant nur eine neue Sitzung starten, indem EapHostPeerBeginSession aufgerufen wird.

Der Aufruf von EapHostPeerBeginSession zum Einrichten der Erneutauthentifizierungssitzung kann über den im func-Parameter angegebenen Rückruf erfolgen und aufgerufen werden, wenn sich der Integritätsstatus ändert. Diese Rückruffunktion gibt dem Bittsteller an, die der GUID zugeordnete Netzwerkauthentifizierung abreißen und erneut authentifizieren.

Eine Verbindung kann über mehrere Sitzungen hinweg beibehalten werden, da EapHostPeerBeginSession eine gültige GUID zum Registrieren der Verbindung bereitstellen kann. Wenn EapHostPeerEndSession aufgerufen wird, wird nur die aktuelle Sitzung beendet. Da die Registrierung mit der GUID nicht beendet wird, bleibt die ursprüngliche Registrierung von EapHostPeerBeginSession intakt. Daher ist die Registrierung über mehrere Sitzungen hinweg wirksam.

Hinweis Das Registrieren der Verbindung bezieht sich auf die Bereitstellung einer gültigen GUID und eines gültigen Rückruffunktionszeigers.

 

Anforderungen

Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	eappapis.h
Bibliothek	Eappprxy.lib
DLL	Eappprxy.dll

Weitere Informationen

EAPHost Supplicant Laufzeitfunktionen

EapHostPeerClearConnection

EapHostPeerEndSession

SSO und PLAP