Função SspiAcceptSecurityContextAsync (sspi.h)

Artigo
08/26/2023

A função SspiAcceptSecurityContextAsync permite que o componente de servidor de um aplicativo de transporte estabeleça de forma assíncrona um contexto de segurança entre o servidor e um cliente remoto. O cliente remoto chama a função SspiInitializeSecurityContextAsync para iniciar de forma assíncrona o processo de estabelecer um contexto de segurança.

Observação

Essa função serve como o equivalente assíncrono àfunção AcceptSecurityContext.

Sintaxe

SECURITY_STATUS SspiAcceptSecurityContextAsync(
  SspiAsyncContext *AsyncContext,
  PCredHandle      phCredential,
  PCtxtHandle      phContext,
  PSecBufferDesc   pInput,
  unsigned long    fContextReq,
  unsigned long    TargetDataRep,
  PCtxtHandle      phNewContext,
  PSecBufferDesc   pOutput,
  unsigned long    *pfContextAttr,
  PTimeStamp       ptsExpiry
);

Parâmetros

AsyncContext

O contexto de chamada assíncrona.

phCredential

Um identificador para as credenciais do servidor. Para recuperar esse identificador, o servidor chama a função SspiAcquireCredentialsHandleAsync com o sinalizador SECPKG_CRED_INBOUND ou SECPKG_CRED_BOTH definido.

phContext

Um ponteiro para uma estrutura CtxtHandle . Na primeira chamada para SspiAcceptSecurityContextAsync, esse ponteiro é NULL. Em chamadas subsequentes, phContext especifica o contexto parcialmente formado retornado no parâmetro phNewContext pela primeira chamada.

pInput

Um ponteiro para uma estrutura SecBufferDesc gerada por uma chamada de cliente para SspiInitializeSecurityContextAsync. A estrutura contém o descritor de buffer de entrada.

O primeiro buffer deve ser do tipo SECBUFFER_TOKEN e conter o token de segurança recebido do cliente. O segundo buffer deve ser do tipo SECBUFFER_EMPTY.

fContextReq

Sinalizadores de bits que especificam os atributos exigidos pelo servidor para estabelecer o contexto.

Consulte AcceptSecurityContext: fContextReq para obter uma lista completa de valores de parâmetro.

TargetDataRep

A representação de dados, como ordenação de bytes, no destino. Esse parâmetro pode ser SECURITY_NATIVE_DREP ou SECURITY_NETWORK_DREP.

phNewContext

Um ponteiro para uma estrutura CtxtHandle . Na primeira chamada para SspiAcceptSecurityContextAsync, esse ponteiro recebe o novo identificador de contexto. Em chamadas subsequentes, phNewContext pode ser o mesmo que o identificador especificado no parâmetro phContext .

pOutput

Um ponteiro para uma estrutura SecBufferDesc que contém o descritor de buffer de saída. Esse buffer é enviado ao cliente para entrada em chamadas adicionais para SspiInitializeSecurityContextAsync. Um buffer de saída pode ser gerado mesmo que a função retorne SEC_E_OK. Qualquer buffer gerado deve ser enviado de volta para o aplicativo cliente.

Na saída, esse buffer recebe um token para o contexto de segurança assíncrona. O token deve ser enviado ao cliente. A função também pode retornar um buffer do tipo SECBUFFER_EXTRA.

pfContextAttr

Um ponteiro para um conjunto de sinalizadores de bits que indicam os atributos do contexto estabelecido.

Consulte AcceptSecurityContext: pfContextAttr para obter descrições dos atributos.

ptsExpiry

Um ponteiro para uma estrutura TimeStamp que recebe o tempo de expiração do contexto.

Consulte AcceptSecurityContext: ptsExpiry.

Valor retornado

Retorna SEC_E_OK se a solicitação assíncrona para estabelecer um contexto de segurança foi enfileirada com êxito para execução. Caso contrário, ele retornará o erro gerado ao tentar enfileirar. Para recuperar o status da operação, use SspiGetAsyncCallStatus.

Se o contexto de segurança recebido do cliente tiver sido aceito, SspiGetAsyncCallStatus retornará SEC_E_OK ou um dos códigos SSPI na tabela abaixo. Caso contrário, ele poderá retornar SEC_I_ASYNC_CALL_PENDING se a chamada ainda estiver em andamento ou qualquer um dos seguintes códigos de erro fatais na segunda tabela abaixo.

Código de retorno	Descrição
SEC_E_INCOMPLETE_MESSAGE 0x80090318L	A função foi bem-sucedida. Os dados no buffer de entrada estão incompletos. O aplicativo deve ler dados adicionais do cliente e chamar SspiAcceptSecurityContextAsync novamente.
SEC_I_COMPLETE_AND_CONTINUE 0x00090314L	A função foi bem-sucedida. O servidor deve chamar CompleteAuthToken e passar o token de saída para o cliente. Em seguida, o servidor deve aguardar um token de retorno do cliente antes de fazer outra chamada para SspiAcceptSecurityContextAsync.
SEC_I_COMPLETE_NEEDED 0x00090313L	A função foi bem-sucedida. O servidor deve concluir a compilação da mensagem do cliente antes de chamar CompleteAuthToken.
SEC_I_CONTINUE_NEEDED 0x00090312L	A função foi bem-sucedida. O servidor deve enviar o token de saída para o cliente e aguardar um token retornado. O token retornado deve ser passado em pInput para outra chamada para SspiAcceptSecurityContextAsync.

Códigos de erro fatais

Código de retorno	Descrição
SEC_E_INSUFFICIENT_MEMORY 0x80090300L	A função falhou. Não há memória suficiente disponível para concluir a ação solicitada.
SEC_E_INTERNAL_ERROR 0x80090304L	A função falhou. Ocorreu um erro que não foi mapeado para um código de erro SSPI.
SEC_E_INVALID_HANDLE 0x80100003L	A função falhou. O identificador passado para a função não é válido.
SEC_E_INVALID_TOKEN 0x80090308L	A função falhou. O token passado para a função não é válido.
SEC_E_LOGON_DENIED 0x8009030CL	Falha no logon.
SEC_E_NO_AUTHENTICATING_AUTHORITY 0x80090311L	A função falhou. Nenhuma autoridade pode ser contatada para autenticação. Isso pode ocorrer devido às seguintes condições: O nome de domínio da parte autenticadora está incorreto. O domínio não está disponível. A relação de confiança falhou.
SEC_E_NO_CREDENTIALS 0x8009030EL	A função falhou. O identificador de credenciais especificado no parâmetro phCredential não é válido.
SEC_E_UNSUPPORTED_FUNCTION 0x80090302L	Falha na função. O parâmetro fContextReq especificou um sinalizador de atributo de contexto (ASC_REQ_DELEGATE ou ASC_REQ_PROMPT_FOR_CREDS) que não era válido.

Comentários

A função SspiAcceptSecurityContextAsync é a equivalente do servidor à função SspiInitializeSecurityContextAsync .

O chamador é responsável por determinar se os atributos de contexto finais são suficientes. Por exemplo, se a confidencialidade (criptografia) foi solicitada, mas não pôde ser estabelecida, alguns aplicativos podem optar por desligar a conexão imediatamente. Se o contexto de segurança não puder ser estabelecido, o servidor deverá liberar o contexto parcialmente criado chamando a função SspiDeleteSecurityContextAsync .

Consulte AcceptSecurityContext para obter comentários adicionais.

Requisitos


Cliente mínimo com suporte	Windows 10, versão 1607 [somente drivers no modo kernel]
Servidor mínimo com suporte	Windows Server 2016 [somente drivers no modo kernel]
Cabeçalho	sspi.h