Função EapHostPeerBeginSession (eappapis.h)

Inicia uma sessão de autenticação EAP. Se a função EapHostPeerBeginSession for bem-sucedida, o chamador também deverá chamar EapHostPeerEndSession para encerrar a sessão de autenticação. A última função deve ser chamada independentemente de funções diferentes de EapHostPeerBeginSession serem bem-sucedidas ou falharem.

Se a nova autenticação for necessária, independentemente do motivo, a interface representada pelo parâmetro pConnectionId não será registrada. Nos casos em que pConnectionId não está registrado, você também deve chamar EapHostPeerClearConnection para remover a conexão.

Nunca mais chame EapHostPeerBeginSession em uma interface sem chamar EapHostPeerEndSession. Somente uma sessão de autenticação pode estar ativa na interface especificada por pConnectionId.

Sintaxe

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

Parâmetros

[in] dwFlags

Uma combinação de sinalizadores EAP que descrevem o novo comportamento da sessão de autenticação EAP.

[in] eapType

Uma estrutura EAP_METHOD_TYPE que especifica o tipo de autenticação EAP a ser usada para esta sessão.

[in] pAttributeArray

Ponteiro para uma estrutura EapAttributes que especifica os atributos EAP da entidade a ser autenticada.

[in] hTokenImpersonateUser

Manipule para o token de representação do usuário a ser usado nesta sessão.

[in] dwSizeofConnectionData

O tamanho, em bytes, do buffer de dados de conexão fornecido em pConnectionData.

[in] pConnectionData

Descreve a configuração usada para autenticação. Os dados de conexão NULL são considerados válidos. O método deve funcionar com a configuração padrão.

[in] dwSizeofUserData

O tamanho, em bytes, do buffer de dados do usuário fornecido em pUserData.

[in] pUserData

Um ponteiro para um buffer de bytes que contém o BLOB de dados de usuário opaco que contém dados de usuário retornados da função EapPeerGetIdentity . Os dados do usuário podem incluir credenciais ou certificados usados para autenticação. pUserData pode ser NULL. A interpretação de um ponteiro NULL depende da implementação de um método. Os dados do usuário consistem em credenciais de usuário ou computador usadas para autenticação. Normalmente, os dados do usuário dependem dos dados de configuração.

Se EAP_FLAG_PREFER_ALT_CREDENTIALS for indicado em dwflags, as credenciais passadas para EapPeerBeginSession serão preferenciais a todas as outras formas de recuperação de credencial, mesmo que os dados de configuração passados para pConnectionData solicitem um modo diferente de recuperação de credencial. Se a passagem de credenciais para EapPeerBeginSession falhar, o EAPHost recorrerá à recuperação de credencial específica do método; nesse caso, as credenciais poderão ser obtidas de um arquivo, logon do Windows ou um repositório de certificados, por exemplo.

O autor do método EAP define as credenciais padrão e as credenciais alternativas. Por exemplo, no caso de EAP-MSCHAPv2 as credenciais padrão são credenciais do Windows obtidas do winlogon e as credenciais alternativas são as credenciais (nome de usuário, senha, domínio) passadas para pUserData.

[in] dwMaxSendPacketSize

O tamanho máximo, em bytes, de um pacote EAP que pode ser enviado durante a sessão.

[in] pConnectionId

Um ponteiro para um valor guid que identifica exclusivamente o adaptador de rede lógica sobre o qual a autenticação do supplicante ocorrerá. Se o supplicante buscar nova autenticação após uma alteração de integridade na NAP, ele deverá fornecer um GUID exclusivo. O parâmetro deve ser NULL quando essa função é chamada por um método de túnel para iniciar seu método interno. Quando o parâmetro pConnectionId é NULL, os parâmetros func e pContextData são ignorados.

[in] func

Um ponteiro de função NotificationHandler que fornece o retorno de chamada usado pelo EAPHost para notificar o supplicante quando a nova autenticação for necessária.

Se o manipulador de funções for NULL, o parâmetro pContextData será ignorado. Se o manipulador de funções for NULL, isso também significa que o chamador não está interessado na notificação de alteração de SoH do QEC (cliente de imposição de quarentena) do EAP.

O código a seguir mostra uma chamada de retorno de chamada notificationHandler .

func(*pConnectionId, pContextData);

[in] pContextData

Um ponteiro para autenticar novamente os dados de contexto que o suplicente associará à conexão quando func for chamado. Este parâmetro pode ser NULL.

[out] pSessionId

Um ponteiro para uma estrutura EAP_SESSIONID que contém o identificador exclusivo para essa sessão de autenticação EAP no servidor EAPHost.

[out] ppEapError

Um ponteiro para o endereço de uma estrutura EAP_ERROR . O endereço deve ser definido como NULL antes de chamar essa função. Se os dados de erro estiverem disponíveis, um ponteiro para o endereço de uma estrutura EAP_ERROR que contenha erros gerados durante a execução dessa chamada de função será recebido. Depois de usar os dados de erro, libere essa memória chamando EapHostPeerFreeEapError.

Valor retornado

Nenhum

Comentários

Se um supplicante EAPHost estiver participando do NAP, o suplicente responderá a alterações no estado de sua integridade de rede. Se esse estado for alterado, o suplicente deverá iniciar uma sessão de nova autenticação da seguinte maneira.

• Se houver uma sessão atual quando ocorrer a nova autenticação, o suplicante deverá derrubar a sessão atual chamando EapHostPeerEndSession e iniciar uma nova sessão chamando EapHostPeerBeginSession.
• Se não houver nenhuma sessão atual com nova autenticação ocorrer ou a sessão anterior já tiver sido encerrada chamando EapHostPeerEndSession, o supplicante só precisará iniciar uma nova sessão chamando EapHostPeerBeginSession.

A chamada para EapHostPeerBeginSession para estabelecer a sessão de reutenticação pode ser feita a partir do retorno de chamada especificado no parâmetro func e chamada quando o estado de integridade é alterado. Essa função de retorno de chamada indica ao suplicante para derrubar a autenticação de rede associada ao GUID e autenticar novamente.

Uma conexão pode ser mantida em várias sessões porque EapHostPeerBeginSession pode fornecer um GUID válido para registrar a conexão. Quando EapHostPeerEndSession é chamado, somente a sessão atual é encerrada. Como o registro com o GUID não foi encerrado, o registro original por EapHostPeerBeginSession permanece intacto. Portanto, o registro é eficaz em várias sessões.

Nota Registrar a conexão refere-se a fornecer um GUID válido e um ponteiro de função de retorno de chamada válido.

 

Requisitos

Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	eappapis.h
Biblioteca	Eappprxy.lib
DLL	Eappprxy.dll

Confira também

Funções em tempo de execução do Supplicante EAPHost

EapHostPeerClearConnection

EapHostPeerEndSession

SSO e PLAP