Função SspiAcquireCredentialsHandleAsyncA (sspi.h)

A função SspiAcquireCredentialsHandleAsyncA adquire de forma assíncrona um identificador para credenciais preexistentes de uma entidade de segurança.

Esse identificador é exigido pelas funções SspiInitializeSecurityContextAsync e SspiAcceptSecurityContextAsync . Elas podem ser credenciais preexistidas, que são estabelecidas por meio de um logon do sistema que não está descrito aqui, ou o chamador pode fornecer credenciais alternativas.

Observação

Essa função serve como o equivalente assíncrono a AcquireCredentialsHandle.

Sintaxe

SECURITY_STATUS SspiAcquireCredentialsHandleAsyncA(
  SspiAsyncContext *AsyncContext,
  LPSTR            pszPrincipal,
  LPSTR            pszPackage,
  unsigned long    fCredentialUse,
  void             *pvLogonId,
  void             *pAuthData,
  SEC_GET_KEY_FN   pGetKeyFn,
  void             *pvGetKeyArgument,
  PCredHandle      phCredential,
  PTimeStamp       ptsExpiry
);

Parâmetros

AsyncContext

O contexto de chamada assíncrona.

pszPrincipal

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome da entidade de segurança cujas credenciais o identificador fará referência assíncrona.

pszPackage

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do pacote de segurança com o qual essas credenciais serão usadas.

Consulte AcquireCredentialsHandleA: pszPackage

fCredentialUse

Um sinalizador que indica como essas credenciais serão usadas. Esse parâmetro pode usar um dos valores a seguir:

Valor	Significado
SECPKG_CRED_INBOUND	Valide uma credencial de servidor de entrada. As credenciais de entrada podem ser validadas usando uma autoridade de autenticação quando SspiInitializeSecurityContextAsync ou SspiAcceptSecurityContextAsync é chamado. Se essa autoridade não estiver disponível, a função falhará e retornará SEC_E_NO_AUTHENTICATING_AUTHORITY. A validação é específica do pacote.
SECPKG_CRED_OUTBOUND	Permitir que uma credencial de cliente local prepare um token de saída.

pvLogonId

Um ponteiro para um LUID ( identificador local exclusivo ) que identifica o usuário. Esse parâmetro é fornecido para processos do sistema de arquivos, como redirecionadores de rede. Este parâmetro pode ser NULL.

pAuthData

Um ponteiro para uma estrutura CREDSSP_CRED que especifica dados de autenticação para pacotes Schannel e Negotiate.

pGetKeyFn

Ponteiro para a função GetKey().

pvGetKeyArgument

Passe para GetKey().

phCredential

Um ponteiro para a estrutura CredHandle que receberá o identificador de credencial.

ptsExpiry

Opcional Um ponteiro para uma estrutura TimeStamp que recebe o tempo em que as credenciais retornadas expiram. O valor da estrutura recebido depende do pacote de segurança, que deve especificar o valor no horário local.

Retornar valor

Retorna SEC_E_OK se a solicitação assíncrona para adquirir um identificador de credencial 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 identificador tiver sido adquirido, SspiGetAsyncCallStatus retornará SEC_E_OK. 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 tabela abaixo.

Código de retorno	Descrição
SEC_E_INSUFFICIENT_MEMORY	Não há memória suficiente disponível para concluir a ação solicitada.
SEC_E_INTERNAL_ERROR	Ocorreu um erro que não foi mapeado para um código de erro SSPI.
SEC_E_NO_CREDENTIALS	Nenhuma credencial está disponível no pacote de segurança
SEC_E_NOT_OWNER	O chamador da função não tem as credenciais necessárias.
SEC_E_SECPKG_NOT_FOUND	O pacote de segurança solicitado não existe.
SEC_E_UNKNOWN_CREDENTIALS	As credenciais fornecidas ao pacote não foram reconhecidas.

Comentários

A função SspiAcquireCredentialsHandleAsyncA retorna um identificador para as credenciais de uma entidade de segurança, como um usuário ou cliente, conforme usado por um pacote de segurança específico. A função pode retornar o identificador para credenciais pré-existidas ou credenciais recém-criadas e devolvê-la. Esse identificador pode ser usado em chamadas subsequentes para as funções SspiAcceptSecurityContextAsync e SspiInitializeSecurityContextAsync .

Em geral, SspiAcquireCredentialsHandleAsyncA não fornece as credenciais de outros usuários conectados ao mesmo computador. No entanto, um chamador com privilégio SE_TCB_NAME pode obter as credenciais de uma sessão de logon existente especificando o LUID ( identificador de logon ) dessa sessão. Normalmente, isso é usado por módulos do modo kernel que devem agir em nome de um usuário conectado.

Um pacote pode chamar a função em pGetKeyFn fornecida pelo transporte em tempo de execução RPC. Se o transporte não der suporte à noção de retorno de chamada para recuperar credenciais, esse parâmetro deverá ser NULL.

Para chamadores do modo kernel, as seguintes diferenças devem ser observadas:

• Os dois parâmetros de cadeia de caracteres devem ser cadeias de caracteres Unicode .
• Os valores de buffer devem ser alocados na memória virtual do processo, não no pool.

Quando terminar de usar as credenciais retornadas, libere a memória usada pelas credenciais chamando a função SspiFreeCredentialsHandleAsync .

Requisitos

Requisito	Valor
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

Confira também

Acquirecredentialshandle

SspiAcceptSecurityContextAsync

SspiFreeCredentialsHandleAsync

SspiInitializeSecurityContextAsync

Funções SSPI