Função AcquireCredentialsHandle (Geral)

A função AcquireCredentialsHandle (Geral) adquire um identificador para credenciais preexistentes de uma entidade de segurança. Esse identificador é exigido pelas funções InitializeSecurityContext (Geral) e AcceptSecurityContext (Geral). Essas podem ser credenciais preexistentes, que são estabelecidas por meio de um logon do sistema que não é descrito aqui, ou o chamador pode fornecer credenciais alternativas.

Para obter informações sobre como usar essa função com um SSP (provedor de suporte de segurança ) específico, consulte os tópicos a seguir.

Sintaxe

SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
  _In_  SEC_CHAR       *pszPrincipal,
  _In_  SEC_CHAR       *pszPackage,
  _In_  ULONG          fCredentialUse,
  _In_  PLUID          pvLogonID,
  _In_  PVOID          pAuthData,
  _In_  SEC_GET_KEY_FN pGetKeyFn,
  _In_  PVOID          pvGetKeyArgument,
  _Out_ PCredHandle    phCredential,
  _Out_ PTimeStamp     ptsExpiry
);

Parâmetros

pszPrincipal [em]

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

Ao usar o SSP Digest, esse parâmetro é opcional.

Ao usar o SSP Schannel, esse parâmetro não é usado e deve ser definido como NULL.

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 sob cujo contexto de segurança ele está sendo executado.

 

pszPackage [em]

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. Este é 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 (General) pode ser chamado com ulAttribute definido como SECPKG_ATTR_PACKAGE_INFO para retornar informações sobre o pacote de segurança em uso.

Ao usar o SSP Digest, defina esse parâmetro como WDIGEST_SP_NAME.

Ao usar o SSP Schannel, defina esse parâmetro como UNISP_NAME.

fCredentialUse [em]

Um sinalizador que indica como essas credenciais serão usadas. Este parâmetro pode ser um dos seguintes valores.

Valor	Significado
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	A segurança não usa credenciais de logon padrão ou credenciais do Gerenciador de Credenciais. Esse valor é suportado apenas pela delegação restrita Negociar. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Este valor não é suportado.
SECPKG_CRED_BOTH	Valide uma credencial de entrada ou use uma credencial local para preparar um token de saída. Este sinalizador habilita ambos os outros sinalizadores. Esse sinalizador não é válido com os SSPs Digest e Schannel.
SECPKG_CRED_INBOUND	Valide uma credencial de servidor de entrada. As credenciais de entrada podem ser validadas usando uma autoridade de autenticação quando InitializeSecurityContext (General) ou AcceptSecurityContext (General) é chamado. Se essa autoridade não estiver disponível, a função falhará e voltará SEC_E_NO_AUTHENTICATING_AUTHORITY. A validação é específica do pacote.
SECPKG_CRED_OUTBOUND	Permita que uma credencial de cliente local prepare um token de saída.
SECPKG_CRED_PROCESS_POLICY_ONLY 0x00000020	A função processa a política do servidor e retorna SEC_E_NO_CREDENTIALS, indicando que o aplicativo deve solicitar credenciais. Esse valor é suportado apenas pela delegação restrita Negociar. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Este valor não é suportado.

 

pvLogonID [em]

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

Ao usar o SSP Schannel, esse parâmetro não é usado e deve ser definido como NULL.

pAuthData [em]

Um ponteiro para dados específicos do pacote. Esse parâmetro pode ser NULL, o que indica que as credenciais padrão para esse pacote de segurança devem ser usadas. Para usar as credenciais fornecidas, passe uma estrutura de SEC_WINNT_AUTH_IDENTITY que inclua essas credenciais nesse parâmetro. O tempo de execução RPC passa o que foi fornecido em RpcBindingSetAuthInfo.

Ao usar o SSP Digest, esse parâmetro é um ponteiro para uma estrutura de SEC_WINNT_AUTH_IDENTITY que contém informações de autenticação a serem usadas para localizar as credenciais.

Ao usar o SSP Schannel, especifique uma estrutura de SCHANNEL_CRED que indique o protocolo a ser usado e as configurações para vários recursos de canal personalizáveis.

Ao usar os pacotes NTLM ou Negociar, os comprimentos máximos de caracteres para nome de usuário, senha e domínio são 256, 256 e 15, respectivamente.

pGetKeyFn [em]

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

pvGetKeyArgument [em]

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

phCredential [saída]

Um ponteiro para uma estrutura CredHandle para receber o identificador de credencial.

ptsExpiração [out]

Um ponteiro para uma estrutura TimeStamp que recebe a hora em que as credenciais retornadas expiram. O valor retornado nessa estrutura de carimbo de data/hora depende da delegação restrita. O pacote de segurança deve retornar esse valor no horário local.

Este parâmetro é definido como um tempo máximo constante. Não há tempo de expiração para contextos ou credenciais de segurançaDigest ou ao usar o SSP Digest.

Ao usar o SSP Schannel, esse parâmetro é opcional. Quando a credencial a ser usada para autenticação é um certificado, esse parâmetro recebe o tempo de expiração desse certificado. Se nenhum certificado for fornecido, um valor de tempo máximo será retornado.

Valor de retorno

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

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

Observações

A função AcquireCredentialsHandle (Geral) retorna um identificador para as credenciais de uma entidade de segurança, como um usuário ou cliente, conforme usado por uma delegação restrita específica. Isso pode ser o identificador para credenciais preexistentes ou a função pode criar um novo conjunto de credenciais e devolvê-lo. Esse identificador pode ser usado em chamadas subsequentes para as funções AcceptSecurityContext (General) e InitializeSecurityContext (General).

Em geral, AcquireCredentialsHandle (Geral) não permite que um processo obtenha um identificador para as credenciais de outros usuários conectados ao mesmo computador. No entanto, um chamador com privilégio SE_TCB_NAME tem a opção de especificar o identificador de logon (LUID) de qualquer token de sessão de logon existente para obter um identificador para as credenciais dessa sessão. Normalmente, isso é usado por módulos de modo kernel que devem agir em nome de um usuário conectado.

Um pacote pode chamar a função em pGetKeyFn fornecida pelo transporte de tempo de execução RPC. Se o transporte não oferecer 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 do pool.

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

Requerimentos

Ver também

Funções SSPI

AcceptSecurityContext (Geral)

InitializeSecurityContext (Geral)

FreeCredentialsHandle