Funzione EapHostPeerBeginSession (eappapis.h)

Articolo
08/23/2023

Avvia una sessione di autenticazione EAP. Se la funzione EapHostPeerBeginSession ha esito positivo, il chiamante deve chiamare anche EapHostPeerEndSession per terminare la sessione di autenticazione. La seconda funzione deve essere chiamata indipendentemente dal fatto che le funzioni diverse da EapHostPeerBeginSession abbiano esito positivo o negativo.

Se è necessaria nuovamente l'autenticazione, indipendentemente dal motivo, l'interfaccia rappresentata dal parametro pConnectionId verrà annullata. Nei casi in cui pConnectionId non è registrato, è necessario chiamare anche EapHostPeerClearConnection per rimuovere la connessione.

Non chiamare mai di nuovo EapHostPeerBeginSession in un'interfaccia senza chiamare EapHostPeerEndSession. Solo una sessione di autenticazione può essere attiva nell'interfaccia specificata da pConnectionId.

Sintassi

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

Parametri

[in] dwFlags

Combinazione di flag EAP che descrivono il nuovo comportamento della sessione di autenticazione EAP.

[in] eapType

Struttura EAP_METHOD_TYPE che specifica il tipo di autenticazione EAP da usare per questa sessione.

[in] pAttributeArray

Puntatore a una struttura EapAttributes che specifica gli attributi EAP dell'entità da autenticare.

[in] hTokenImpersonateUser

Gestire il token di rappresentazione utente da usare in questa sessione.

[in] dwSizeofConnectionData

Dimensioni, in byte, del buffer dati di connessione fornito in pConnectionData.

[in] pConnectionData

Descrive la configurazione usata per l'autenticazione. I dati di connessione NULL sono considerati validi. Il metodo deve funzionare con la configurazione predefinita.

[in] dwSizeofUserData

Dimensioni, in byte, del buffer dati utente fornito in pUserData.

[in] pUserData

Puntatore a un buffer di byte contenente il BLOB di dati utente opaco contenente i dati utente restituiti dalla funzione EapPeerGetIdentity . I dati utente possono includere credenziali o certificati usati per l'autenticazione. pUserData può essere NULL. L'interpretazione di un puntatore NULL dipende dall'implementazione di un metodo. I dati utente sono costituiti da credenziali utente o computer usate per l'autenticazione. In genere, i dati utente dipendono dai dati di configurazione.

Se EAP_FLAG_PREFER_ALT_CREDENTIALS è indicato in dwflags, le credenziali passate a EapPeerBeginSession sono preferite a tutte le altre forme di recupero delle credenziali, anche se i dati di configurazione passati a pConnectionData richiede una modalità diversa di recupero delle credenziali. Se il passaggio delle credenziali in EapPeerBeginSession ha esito negativo, EAPHost si applica al metodo specifico recupero delle credenziali, in questo caso le credenziali potrebbero essere ottenute da un file, un account di accesso di Windows o un archivio certificati, ad esempio.

L'autore del metodo EAP definisce sia le credenziali predefinite che le credenziali alternative. Ad esempio, nel caso di EAP-MSCHAPv2 le credenziali predefinite sono le credenziali di Windows ottenute da winlogon e le credenziali alternative sono le credenziali (nome utente, password, dominio) passate in pUserData.

[in] dwMaxSendPacketSize

Dimensioni massime, in byte, di un pacchetto EAP che può essere inviato durante la sessione.

[in] pConnectionId

Puntatore a un valore GUID che identifica in modo univoco l'interfaccia di rete logica su cui verrà eseguita l'autenticazione del supplicante. Se il supplicant cerca nuovamente l'autenticazione dopo una modifica dell'integrità della rete, deve fornire un GUID univoco. Il parametro deve essere NULL quando questa funzione viene chiamata da un metodo di tunneling per avviare il relativo metodo interno. Quando il parametro pConnectionId è NULL, i parametri func e pContextData vengono ignorati.

[in] func

Puntatore alla funzione NotificationHandler che fornisce il callback usato da EAPHost per inviare una notifica alla supplicante quando è necessaria l'autenticazione di nuovo.

Se il gestore delle funzioni è NULL, il parametro pContextData viene ignorato. Se il gestore delle funzioni è NULL, significa anche che il chiamante non è interessato alla notifica di modifica SoH dal client di applicazione della quarantena EAP (QEC).

Il codice seguente mostra una chiamata di callback di NotificationHandler .

func(*pConnectionId, pContextData);

[in] pContextData

Puntatore ai dati del contesto di autenticazione che il supplicante associa alla connessione quando viene chiamato func . Questo parametro può essere NULL.

[out] pSessionId

Puntatore a una struttura di EAP_SESSIONID che contiene l'handle univoco per questa sessione di autenticazione EAP nel server EAPHost.

[out] ppEapError

Puntatore all'indirizzo di una struttura EAP_ERROR . L'indirizzo deve essere impostato su NULL prima di chiamare questa funzione. Se sono disponibili dati di errore, viene ricevuto un puntatore all'indirizzo di una struttura EAP_ERROR contenente eventuali errori generati durante l'esecuzione di questa chiamata di funzione. Dopo aver usato i dati di errore, liberare questa memoria chiamando EapHostPeerFreeEapError.

Valore restituito

nessuno

Osservazioni

Se un supplicante EAPHost partecipa a NAP, il supplicant risponderà alle modifiche nello stato dell'integrità della rete. Se lo stato cambia, il supplicant deve quindi avviare una sessione di riutenticazione come indicato di seguito.

Se si verifica una sessione corrente quando si verifica nuovamente l'autenticazione, il supplicant deve ridurre la sessione corrente chiamando EapHostPeerEndSession e quindi avvia una nuova sessione chiamando EapHostPeerBeginSession.
Se non si verifica alcuna sessione corrente con l'autenticazione di nuovo oppure la sessione precedente è già stata terminata chiamando EapHostPeerEndSession, è necessario avviare una nuova sessione chiamando EapHostPeerBeginSession.

La chiamata a EapHostPeerBeginSession per stabilire la sessione di riutenticazione può essere eseguita dal callback specificato nel parametro func e chiamato quando lo stato di integrità cambia. Questa funzione di callback indica al supplicante di rimuovere l'autenticazione di rete associata al GUID e ripetere l'autenticazione.

Una connessione può essere mantenuta tra più sessioni perché EapHostPeerBeginSession può fornire un GUID valido per registrare la connessione. Quando viene chiamato EapHostPeerEndSession , viene terminata solo la sessione corrente. Poiché la registrazione con il GUID non viene terminata, la registrazione originale di EapHostPeerBeginSession rimane intatta. Pertanto, la registrazione è effettiva in più sessioni.

Nota La registrazione della connessione fa riferimento alla specifica di un GUID valido e di un puntatore della funzione di callback valido.

Requisiti


Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	eappapis.h
Libreria	Eappprxy.lib
DLL	Eappprxy.dll

Vedi anche

Funzioni di run-time supplicant di EAPHost

EapHostPeerClearConnection

EapHostPeerEndSession

SSO e PLAP

Condividi tramite