Função AcquireCredentialsHandle (Schannel)
A função AcquireCredentialsHandle (Schannel) adquire um identificador para pré-existentes credenciais de uma entidade de segurança. Esse identificador é exigido pelas funções InitializeSecurityContext (Schannel) e AcceptSecurityContext (Schannel ). 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 a coleta de credenciais.
Sintaxe
SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
_In_opt_ SEC_CHAR *pszPrincipal,
_In_ SEC_CHAR *pszPackage,
_In_ ULONG fCredentialUse,
_In_opt_ PLUID pvLogonID,
_In_opt_ PVOID pAuthData,
_In_opt_ SEC_GET_KEY_FN pGetKeyFn,
_In_opt_ PVOID pvGetKeyArgument,
_Out_ PCredHandle phCredential,
_Out_opt_ PTimeStamp ptsExpiry
);
Parâmetros
pszPrincipal[in, optional]
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.
Ao usar o SSP do 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 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 (Schannel) 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 do Schannel, defina esse parâmetro como UNISP_NAME.
Observação
Os chamadores do modo kernel que encontram problemas ao chamar InitializeSecurityContext (Schannel) depois de chamar AcquireCredentialsHandle (Schannel) podem, como alternativa, definir pszPackage como SCHANNEL_NAME.
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 | Valide uma credencial de servidor de entrada. As credenciais de entrada podem ser validadas usando uma autoridade de autenticação quando InitializeSecurityContext (Schannel) ou AcceptSecurityContext (Schannel) são chamadas. 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[in, optional]
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. Esse parâmetro pode ser NULL.
Ao usar o SSP do Schannel, esse parâmetro não é usado e deve ser definido como NULL.
pAuthData[in, optional]
Um ponteiro para dados específicos do pacote. Esse parâmetro pode ser NULL, 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 do RPC passa o que foi fornecido em RpcBindingSetAuthInfo.
Ao usar o SSP do Schannel, especifique uma estrutura SCH_CREDENTIALS que indique o protocolo a ser usado e as configurações para vários recursos de canal personalizáveis.
pGetKeyFn[in, optional]
Esse parâmetro não é usado e deve ser definido como NULL.
pvGetKeyArgument[in, optional]
Esse parâmetro não é usado e deve ser definido como NULL.
phCredential[out]
Um ponteiro para uma estrutura CredHandle para receber o identificador de credencial.
ptsExpiry[out, optional]
Um ponteiro para uma estrutura TimeStamp que recebe o tempo em que as credenciais retornadas expiram. O valor retornado nesta estrutura TimeStamp depende da delegação restrita. O pacote de segurança deve retornar esse valor no horário local.
Ao usar o SSP do 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 tiver sido fornecido, um valor de tempo máximo será retornado.
Retornar valor
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.
| 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 na delegação restrita. |
| 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 ao pacote não foram reconhecidas. |
Comentários
A função AcquireCredentialsHandle (Schannel) 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. Esse pode ser o identificador para credenciais pré-existidos 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 (Schannel) e InitializeSecurityContext (Schannel ).
Em geral, AcquireCredentialsHandle (Schannel) 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 LUID (identificador de logon) 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 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 XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| parâmetro | Sspi.h (inclua Security.h) |
| Biblioteca | Secur32.lib |
| DLL | Secur32.dll |
| Nomes Unicode e ANSI | AcquireCredentialsHandleW (Unicode) e AcquireCredentialsHandleA (ANSI) |
Confira também
AcceptSecurityContext (Schannel)