Função SspiInitializeSecurityContextAsyncA (sspi.h)

Artigo
08/26/2023

A função SspiInitializeSecurityContextAsyncA inicia o lado do cliente, contexto de segurança de saída de um identificador de credencial. A função é usada para criar um contexto de segurança entre o aplicativo cliente e um par remoto. SspiInitializeSecurityContextAsyncA retorna um token que o cliente deve passar para o par remoto, que o par, por sua vez, envia para a implementação de segurança local por meio da chamada SspiAcceptSecurityContextAsync .

Nota

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

Sintaxe

SECURITY_STATUS SspiInitializeSecurityContextAsyncA(
  SspiAsyncContext *AsyncContext,
  PCredHandle      phCredential,
  PCtxtHandle      phContext,
  LPSTR            pszTargetName,
  unsigned long    fContextReq,
  unsigned long    Reserved1,
  unsigned long    TargetDataRep,
  PSecBufferDesc   pInput,
  unsigned long    Reserved2,
  PCtxtHandle      phNewContext,
  PSecBufferDesc   pOutput,
  unsigned long    *pfContextAttr,
  PTimeStamp       ptsExpiry
);

Parâmetros

AsyncContext

O contexto de chamada assíncrona.

phCredential

Um identificador para as credenciais retornadas por AcquireCredentialsHandle. Esse identificador é usado para criar o contexto de segurança .

phContext

Um ponteiro para uma estrutura CtxtHandle existente.

pszTargetName

Um ponteiro para uma cadeia de caracteres terminada em nulo que indica o destino do contexto. O conteúdo da cadeia de caracteres é pacote de segurança específico, conforme descrito na tabela a seguir. Esta lista não é completa. SSPs adicionais do sistema e SSPs de terceiros podem ser adicionados a um sistema.

SSP em uso	Significado
Digest	Cadeia de caracteres terminada em nulo que identifica exclusivamente o URI do recurso solicitado. A cadeia de caracteres deve ser composta de caracteres permitidos em um URI e deve ser representável pelo conjunto de códigos ASCII dos EUA. A codificação percentual pode ser usada para representar caracteres fora do conjunto de códigos ASCII dos EUA.
Kerberos ou negociar	O SPN (nome da entidade de serviço) ou o contexto de segurança do servidor de destino.
NTLM	O SPN (nome da entidade de serviço) ou o contexto de segurança do servidor de destino.
Schannel/SSL	Cadeia de caracteres terminada em nulo que identifica exclusivamente o servidor de destino. O Schannel usa esse valor para verificar o certificado do servidor. O Schannel também usa esse valor para localizar a sessão no cache de sessão ao restabelecer uma conexão. A sessão armazenada em cache será usada somente se todas as seguintes condições forem atendidas: O nome de destino é o mesmo. A entrada de cache não expirou. O processo de aplicativo que chama a função é o mesmo. A sessão de logon é a mesma. O identificador de credencial é o mesmo.

fContextReq

Sinalizadores de bits que indicam solicitações para o contexto.

Consulte InitializeSecurityContext: fContextReq para obter uma lista de valores de sinalizador e seus significados.

Reserved1

Esse parâmetro é reservado e deve ser definido como zero.

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.

pInput

Um ponteiro para uma estrutura de SecBufferDesc que contém ponteiros para os buffers fornecidos como entrada para o pacote.

Reserved2

Esse parâmetro é reservado e deve ser definido como zero.

phNewContext

Um ponteiro para uma estrutura de CtxtHandle.

pOutput

Um ponteiro para uma estrutura SecBufferDesc que contém ponteiros para a estrutura secBuffer que recebe os dados de saída.

pfContextAttr

Um ponteiro para uma variável para receber um conjunto de sinalizadores de bits que indicam os atributos do contexto estabelecido. Para obter uma descrição dos vários atributos, consulte Requisitos de Contexto.

ptsExpiry

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

Valor de retorno

Retorna SEC_E_OK se a solicitação assíncrona para estabelecer um contexto de segurança tiver sido enfileirada com êxito para execução, caso contrário, retornará o erro gerado ao tentar enfileira-lo. Para recuperar o status da operação, use SspiGetAsyncCallStatus.

Se o contexto de segurança recebido do servidor 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_I_COMPLETE_AND_CONTINUE 0x00090314L	O cliente deve chamar CompleteAuthToken e passar o token de saída para o servidor. Em seguida, o cliente aguarda um token retornado e o passa, em outra chamada, para SspiInitializeSecurityContextAsyncA.
SEC_I_COMPLETE_NEEDED 0x00090313L	O cliente deve concluir a compilação da mensagem do servidor antes de chamar CompleteAuthToken.
SEC_I_CONTINUE_NEEDED 0x00090312L	O cliente deve enviar o token de saída para o servidor e aguardar um token de retorno. Em seguida, o token retornado é passado em outra chamada para SspiInitializeSecurityContextAsyncA. O token de saída pode estar vazio.
SEC_I_INCOMPLETE_CREDENTIALS	Use com o Schannel. O servidor solicitou a autenticação do cliente e as credenciais fornecidas não incluem um certificado ou o certificado não foi emitido por uma autoridade de certificação confiável pelo servidor.
SEC_E_INCOMPLETE_MESSAGE 0x80090318L	Os dados de toda a mensagem não foram lidos do fio. Quando esse valor é retornado, o buffer pInput contém uma estrutura secBuffer com um membro BufferType de SECBUFFER_MISSING. O membro cbBuffer do SecBuffer contém um valor que indica o número de bytes adicionais que a função deve ler do cliente antes que essa função seja bem-sucedida. Embora esse número nem sempre seja preciso, usá-lo pode ajudar a melhorar o desempenho evitando várias chamadas para essa função.
SEC_E_OK 0x00000000L	O contexto de segurança recebido do cliente foi aceito. Se a função gerou um token de saída, o token deverá ser enviado para o servidor.

Códigos de erro fatais

Código de retorno	Descrição
SEC_E_INSUFFICIENT_MEMORY 0x80090300L	Não há memória suficiente disponível para concluir a ação solicitada.
SEC_E_INTERNAL_ERROR 0x80090304L	Ocorreu um erro que não foi mapeado para um código de erro SSPI.
SEC_E_INVALID_HANDLE 0x80100003L	O identificador passado para a função não é válido.
SEC_E_INVALID_TOKEN 0x80090308L	O erro ocorre devido a um token de entrada malformado, como um token corrompido em trânsito, um token de tamanho incorreto ou um token passado para o pacote de segurança incorreto. Passar um token para o pacote errado pode acontecer se o cliente e o servidor não negociassem o pacote de segurança adequado.
SEC_E_LOGON_DENIED 0x8009030CL	Falha no logon.
SEC_E_NO_AUTHENTICATING_AUTHORITY 0x80090311L	Nenhuma autoridade pode ser contatada para autenticação. O nome de domínio da parte de autenticação pode estar errado, o domínio pode ser inacessível ou pode ter havido uma falha de relação de confiança.
SEC_E_NO_CREDENTIALS 0x8009030EL	Nenhuma credenciais está disponível no pacote de segurança.
SEC_E_TARGET_UNKNOWN	O destino não foi reconhecido.
SEC_E_UNSUPPORTED_FUNCTION 0x80090302L	Um sinalizador de atributo de contexto que não é válido (ISC_REQ_DELEGATE ou ISC_REQ_PROMPT_FOR_CREDS) foi especificado no parâmetro fContextReq.
SEC_E_WRONG_PRINCIPAL	A entidade de segurança que recebeu a solicitação de autenticação não é a mesma passada para o parâmetro pszTargetName. Isso indica uma falha na autenticação mútua.

Observações

Consulte InitializeSecurityContext para obter comentários completos.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 10, versão 1607 [somente drivers no modo kernel]
servidor com suporte mínimo	Windows Server 2016 [somente drivers no modo kernel]
cabeçalho	sspi.h

Consulte também

SspiAcceptSecurityContextAsync

SspiAcquireCredentialsHandleAsync

Compartilhar via