Função SspiAcquireCredentialsHandleAsyncW (sspi.h)
A função SspiAcquireCredentialsHandleAsyncW 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 a contraparte assíncrona para AcquireCredentialsHandle.
Sintaxe
SECURITY_STATUS SspiAcquireCredentialsHandleAsyncW(
SspiAsyncContext *AsyncContext,
PSECURITY_STRING pszPrincipal,
PSECURITY_STRING 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 de forma assíncrona.
Observação
Se o processo que solicita o identificador não tiver acesso às credenciais, a função retornará um erro. Uma cadeia de caracteres nula indica que o processo requer um identificador para as credenciais do usuário em cujo contexto de segurança ele está executando.
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. Esse é um nome de pacote de segurança retornado no membro Name de uma estrutura SecPkgInfo retornada pela função EnumerateSecurityPackages . Depois que um contexto é estabelecido, QueryContextAttributes (CredSSP) pode ser chamado com ulAttribute definido como SECPKG_ATTR_PACKAGE_INFO para retornar informações sobre o pacote de segurança em uso.
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 a hora 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.
Valor retornado
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 para o pacote não foram reconhecidas. |
Comentários
A função SspiAcquireCredentialsHandleAsyncW 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 retorná-la. Esse identificador pode ser usado em chamadas subsequentes para as funções SspiAcceptSecurityContextAsync e SspiInitializeSecurityContextAsync .
Em geral, SspiAcquireCredentialsHandleAsyncW não fornece as credenciais de outros usuários conectados ao mesmo computador. No entanto, um chamador com privilégio de 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
| 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
SspiAcceptSecurityContextAsync
SspiFreeCredentialsHandleAsync