Função AcquireCredentialsHandle (CredSSP)

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

Observação

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

Sintaxe

SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandle(
  _In_opt_   SEC_CHAR       *pszPrincipal,
  _In_       SEC_CHAR       *pszPackage,
  _In_       unsigned long  fCredentialUse,
  _In_opt_   void           *pvLogonID,
  _In_opt_   void           *pAuthData,
  _In_opt_   SEC_GET_KEY_FN pGetKeyFn,
  _Reserved_ void           *pvGetKeyArgument,
  _Out_      PCredHandle    phCredential,
  _Out_opt_  PTimeStamp     ptsExpiry
);

Parâmetros

pszPrincipal [in, opcional]

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á executando.

pszPackage [in]

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 [in]

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
0x0		 Permitir que uma credencial de cliente local prepare um token de saída.

pvLogonId [in, opcional]

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

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

pGetKeyFn [in, opcional]

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

pvGetKeyArgument [in, opcional]

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

phCredential [out]

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

ptsExpiry [out, 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

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

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]
Cabeçalho Sspi.h (incluir Security.h)
Biblioteca Secur32.lib
DLL Secur32.dll
Nomes Unicode e ANSI AcquireCredentialsHandleW (Unicode) e AcquireCredentialsHandleA (ANSI)

Confira também