Função AcquireCredentialsHandleA (sspi.h)

A função AcquireCredentialsHandle (CredSSP) adquire um identificador para pré-existente credenciais de uma entidade de segurança . Esse identificador é exigido pelas funções InitializeSecurityContext (CredSSP) e AcceptSecurityContext (CredSSP). Elas podem ser pré-existentes credenciais, 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 Este não é um "logon na rede" e não implica coleta de credenciais.

 

Sintaxe

SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandleA(
  [in, optional]  LPSTR          pszPrincipal,
  [in]            LPSTR          pszPackage,
  [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

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

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á sendo executado.

 

[in] 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 Name membro 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.

[in] fCredentialUse

Um sinalizador que indica como essas credenciais serão usadas. Esse parâmetro pode ser 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). 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 ( de identificador localmente exclusivo) que identifica o usuário. Esse parâmetro é fornecido para processos do sistema de arquivos, como redirecionadores de rede. Esse 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 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.

Valor de retorno

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 credenciais 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.

Observações

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 devolvê-la. Esse identificador pode ser usado em chamadas subsequentes para o AcceptSecurityContext (CredSSP) e funções de 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 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 no modo kernel que devem agir em nome de um usuário conectado.

Um pacote pode chamar a função em pGetKeyFn fornecido pelo transporte em tempo de execução do 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2008 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	sspi.h (inclua Security.h)
biblioteca	Secur32.lib
de DLL	Secur32.dll

Consulte também

AcceptSecurityContext (CredSSP)

FreeCredentialsHandle

InitializeSecurityContext (CredSSP)

Funções SSPI