Função AcquireCredentialsHandleW (sspi.h)

  • Artigo

A função AcquireCredentialsHandle (CredSSP) adquire um identificador para credenciais preexistentes de uma entidade de segurança. Esse identificador é exigido pelas funções InitializeSecurityContext (CredSSP) e AcceptSecurityContext (CredSSP ). 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.

Nota Isso não é um "logon na rede" e não implica na coleta de credenciais.
 

Sintaxe

KSECDDDECLSPEC SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandleW(
                  PSECURITY_STRING pPrincipal,
                  PSECURITY_STRING pPackage,
  [in]            unsigned long    fCredentialUse,
  [in, optional]  void             *pvLogonId,
  [in, optional]  void             *pAuthData,
  [in, optional]  SEC_GET_KEY_FN   pGetKeyFn,
  [in, optional]  void             *pvGetKeyArgument,
  [out]           PCredHandle      phCredential,
  [out, optional] PTimeStamp       ptsExpiry
);

Parâmetros

pPrincipal

TBD

pPackage

TBD

[in] 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
0x1
 Valide uma credencial de servidor de entrada. As credenciais de entrada podem ser validadas usando uma autoridade de autenticação quando InitializeSecurityContext (CredSSP) ou AcceptSecurityContext (CredSSP) é 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
0x2
 Permitir que uma credencial de cliente local prepare um token de saída.

[in, optional] 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.

[in, optional] pAuthData

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

[in, optional] pGetKeyFn

Reservado. Esse parâmetro não é usado e deve ser definido como NULL.

[in, optional] pvGetKeyArgument

Reservado. Esse parâmetro deve ser definido como NULL.

[out] phCredential

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

[out, optional] ptsExpiry

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.

Retornar valor

Se a função for bem-sucedida, ela retornará SEC_E_OK.

Se a função falhar, ela retornará um dos seguintes códigos de erro.

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 AcquireCredentialsHandle (CredSSP) 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 AcceptSecurityContext (CredSSP) e InitializeSecurityContext (CredSSP ).

Em geral, AcquireCredentialsHandle (CredSSP) 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 FreeCredentialsHandle .

Observação

O cabeçalho sspi.h define AcquireCredentialsHandle como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
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 sspi.h (inclua Security.h)
Biblioteca Secur32.lib
DLL Secur32.dll

Confira também

AcceptSecurityContext (CredSSP)

FreeCredentialsHandle

InitializeSecurityContext (CredSSP)

Funções SSPI