Função CredUICmdLinePromptForCredentialsW (wincred.h)
A função CredUICmdLinePromptForCredentials solicita e aceita informações de credenciais de um usuário que trabalha em um aplicativo de linha de comando (console). O nome e a senha digitados pelo usuário são passados de volta para o aplicativo de chamada para verificação.
Sintaxe
CREDUIAPI DWORD CredUICmdLinePromptForCredentialsW(
[in] PCWSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PWSTR UserName,
[in] ULONG ulUserBufferSize,
[in, out] PWSTR pszPassword,
[in] ULONG ulPasswordBufferSize,
[in, out] PBOOL pfSave,
[in] DWORD dwFlags
);
Parâmetros
[in] pszTargetName
Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome do destino para as credenciais, normalmente um nome de servidor. Para conexões DFS, essa cadeia de caracteres é do formato ServerName\ShareName. O parâmetro pszTargetName é usado para identificar as informações de destino e é usado para armazenar e recuperar a credencial.
[in] pContext
Atualmente reservado e deve ser NULL.
[in, optional] dwAuthError
Especifica por que a solicitação de credenciais é necessária. Um chamador pode passar esse parâmetro de erro do Windows, retornado por outra chamada de autenticação, para permitir que a caixa de diálogo acomode determinados erros. Por exemplo, se a senha expirou status código for passado, a caixa de diálogo solicitará que o usuário altere a senha na conta.
[in, out] UserName
Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome de usuário da credencial. Se uma cadeia de caracteres de comprimento diferente de zero for especificada para pszUserName, o usuário será solicitado apenas para a senha. No caso de credenciais diferentes de nome de usuário/senha, um formato marshaled da credencial pode ser passado. Essa cadeia de caracteres é criada chamando CredMarshalCredential.
Essa função grava o nome fornecido pelo usuário nesse buffer, copiando um máximo de caracteres ulUserNameMaxChars . A cadeia de caracteres nesse formato pode ser convertida no formato de nome de usuário/senha chamando a função CredUIParseUsername . A cadeia de caracteres em seu formato marshaled pode ser passada diretamente para um SSP ( provedor de suporte de segurança ).
Se o sinalizador CREDUI_FLAGS_DO_NOT_PERSIST não for especificado, o valor retornado nesse parâmetro será de um formulário que não deve ser inspecionado, impresso ou persistente além de passá-lo para CredUIParseUsername. Os resultados subsequentes de CredUIParseUsername só podem ser passados para uma API de autenticação do lado do cliente, como WNetAddConnection ou a API do SSP.
[in] ulUserBufferSize
O número máximo de caracteres que podem ser copiados para pszUserName , incluindo o caractere nulo de terminação.
[in, out] pszPassword
Um ponteiro para uma cadeia de caracteres terminada em nulo que contém a senha das credenciais. Se uma cadeia de caracteres de comprimento diferente de zero for especificada para pszPassword, o parâmetro de senha será preenchido previamente com a cadeia de caracteres.
Essa função grava a senha fornecida pelo usuário nesse buffer, copiando um máximo de caracteres ulPasswordMaxChars . Se o sinalizador CREDUI_FLAGS_DO_NOT_PERSIST não for especificado, o valor retornado nesse parâmetro será de um formulário que não deve ser inspecionado, impresso ou persistente além de passá-lo para uma função de autenticação do lado do cliente, como WNetAddConnection ou uma função SSP.
Quando terminar de usar a senha, limpe a senha da memória chamando a função SecureZeroMemory . Para obter mais informações sobre como proteger senhas, consulte Manipulando senhas.
[in] ulPasswordBufferSize
O número máximo de caracteres que podem ser copiados para pszPassword , incluindo o caractere nulo de terminação.
[in, out] pfSave
Um ponteiro para um BOOL que especifica o estado inicial da mensagem Salvar e recebe o estado da mensagem Salvar depois que o usuário responde ao prompt de comando. Se pfSave não for NULL e CredUIPromptForCredentials retornar NO_ERROR, pfSave retornará o estado da mensagem Salvar . Se o sinalizador CREDUI_FLAGS_PERSIST for especificado, a mensagem Salvar não será exibida, mas será considerada "y". Se o sinalizador CREDUI_FLAGS_DO_NOT_PERSIST for especificado e CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX não for especificado, a mensagem Salvar não será exibida, mas será considerada como "n".
[in] dwFlags
Um valor DWORD que especifica um comportamento especial para essa função. Esse valor pode ser uma combinação OR bit a bit de zero ou mais dos valores a seguir.
| Valor | Significado |
|---|---|
|
Exiba uma interface do usuário se as credenciais puderem ser retornadas de uma credencial existente no gerenciador de credenciais. Esse sinalizador só será permitido se CREDUI_FLAGS_GENERIC_CREDENTIALS também for especificado e for usado apenas em conjunto com CREDUI_FLAGS_GENERIC_CREDENTIALS. |
|
Não exiba a mensagem de salvamento ou armazene as credenciais.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX também pode ser passado para exibir apenas a mensagem de salvamento e retornar o resultado em pfSave. |
|
Solicitar nome de usuário/senha. Se o parâmetro pszUserName for especificado, o nome de usuário será omitido. Se a credencial for mantida, armazene o nome de usuário passado com a credencial. |
|
Especifica que o chamador chamará CredUIConfirmCredentials para determinar se as credenciais retornadas são realmente válidas. Isso garante que as credenciais que não são válidas não sejam salvas no gerenciador de credenciais. Especifique esse sinalizador, a menos que CREDUI_FLAGS_DO_NOT_PERSIST seja especificado. |
|
Considere as credenciais inseridas pelo usuário como uma credencial genérica. |
|
Ignore silenciosamente esse sinalizador. |
|
Não mostre a mensagem de salvamento, mas salve a credencial como se o usuário respondeu "y". |
|
Ignore silenciosamente esse sinalizador. |
|
Reservado para uso futuro; não passe esse sinalizador. |
|
Use uma cartão inteligente e solicite um PIN. Se mais de uma cartão inteligente estiver disponível, selecione uma delas. Se o parâmetro pszUserName passar uma cadeia de caracteres que não está vazia, a cadeia de caracteres deverá corresponder ao UPN associado ao certificado em um dos cartões inteligentes. Um UPN corresponde se a cadeia de caracteres corresponde a todo o UPN no certificado ou se a cadeia de caracteres corresponde à parte à esquerda do sinal de at (@) no UPN do certificado. Se houver uma correspondência, o cartão inteligente correspondente será selecionado. |
|
Esse sinalizador é significativo apenas na localização de uma credencial correspondente para pré-armazenar a caixa de diálogo, caso a autenticação falhe. Quando esse sinalizador for especificado, as credenciais curinga não serão correspondidas. Ele não tem efeito ao escrever uma credencial. CredUI não cria credenciais que contenham caracteres curinga. Qualquer encontrado foi criado explicitamente pelo usuário ou criado programaticamente, como acontece quando uma conexão RAS é feita. |
|
Exiba a mensagem de salvamento e retorne TRUE no parâmetro pfSave out se o usuário responder "y", FALSE se o usuário responder "n". CREDUI_FLAGS_DO_NOT_PERSIST deve ser especificado para usar esse sinalizador. |
|
A credencial é uma credencial executar como. O parâmetro pszTargetName especifica o nome do comando ou programa que está sendo executado. Ele é usado apenas para fins de solicitação. |
Valor retornado
O valor retornado é um DWORD e pode ser um dos valores a seguir.
| Valor | Descrição |
|---|---|
|
Essa status é retornada para qualquer uma das combinações de sinalizadores que não são válidas. |
|
PszTargetName é NULL, a cadeia de caracteres vazia ou maior que CREDUI_MAX_DOMAIN_LENGTH ou pUiInfo não é NULL e a estrutura CredUI_INFO apontada não atendeu a um dos seguintes requisitos:
|
|
O gerenciador de credenciais não pode ser usado. Normalmente, esse erro é tratado chamando CredUICmdLinePromptForCredentials e passando o sinalizador CREDUI_FLAGS_DO_NOT_PERSIST. |
|
O usuário escolheu OK. As variáveis pszUserName, pszPassword e pfSave retornarão os valores documentados anteriormente. |
Comentários
Os sinalizadores CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE e CREDUI_FLAGS_EXCLUDE_CERTIFICATE são mutuamente exclusivos.
Se CREDUI_FLAGS_DO_NOT_PERSIST for especificado, pszTargetName deverá ser especificado ou uiInfo-pszMessageText> e uiInfo-pszCaption> deverão ser especificados.
Os sinalizadores CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS e CREDUI_FLAGS_GENERIC_CREDENTIALS são mutuamente exclusivos. Se nenhum for especificado, a credencial será uma credencial de domínio.
Se CREDUI_FLAGS_GENERIC_CREDENTIALS não for especificado ou CREDUI_FLAGS_COMPLETE_USERNAME for especificado, o nome digitado será verificado. A sintaxe verificada significa que as mesmas regras são usadas como estão implícitas por CredUIParseUserName. Se o nome digitado não for válido, o usuário será solicitado a fornecer um válido. Se a parte de domínio do nome digitado estiver ausente, uma será fornecida com base no nome de destino.
Se CREDUI_FLAGS_GENERIC_CREDENTIALS for especificado e CREDUI_FLAGS_VALIDATE_USERNAME também for especificado, o nome digitado será verificado. Se o nome digitado não for válido, o usuário será solicitado a fornecer um válido.
Se CREDUI_FLAGS_GENERIC_CREDENTIALS for especificado e nem CREDUI_FLAGS_COMPLETE_USERNAME nem CREDUI_FLAGS_VALIDATE_USERNAME for especificado, o nome digitado não será verificado de forma alguma.
Se nem CREDUI_FLAGS_PERSIST nem CREDUI_FLAGS_DO_NOT_PERSIST estiverem definidos, a mensagem de salvamento será mostrada e controlará se a credencial será salva ou não.
Se CREDUI_FLAGS_PROMPT_FOR_SAVE for especificado, o parâmetro pfSave não deverá ser NULL.
Os sinalizadores CREDUI_FLAGS_REQUIRE_SMARTCARD e CREDUI_FLAGS_EXCLUDE_CERTIFICATES são mutuamente exclusivos. CredUICmdLinePromptForCredentials dá suporte à solicitação de um certificado de cartão inteligente ou uma credencial baseada em senha. Ele não dá suporte a certificados que não são certificados de cartão inteligentes ou solicitação para ambos em uma única chamada.
Modos de chamada
- O chamador tentará acessar o recurso de destino, chamar credui (passando uma descrição do recurso de destino e o status de falha), chamar CredUIParseUserName, acessar o recurso de destino novamente e, em seguida, chamar CredUIConfirmCredentials.
- O chamador pode solicitar credenciais sem acessar nenhum recurso passando CREDUI_FLAGS_DO_NOT_PERSIST.
Informações de destino são informações sobre o local do recurso a ser acessado. Para obter uma lista de todos os nomes de destino potenciais para um recurso, chame CredGetTargetInfo. CredGetTargetInfo retorna informações que foram armazenadas em cache pelo pacote de autenticação Negotiate, NTLM ou Kerberos quando um desses pacotes foi usado para autenticar no destino nomeado. CredGetTargetInfo retorna alguns ou todos os seguintes nomes para o destino:
- Nome do servidor NetBIOS do computador
- Nome do servidor DNS do computador
- Nome de domínio NetBIOS do domínio ao qual o computador pertence
- Nome de domínio DNS do domínio ao qual o computador pertence
- Nome da árvore DNS da árvore à qual o computador pertence
- Nome do pacote que coletou as informações
As credenciais são armazenadas no gerenciador de credenciais com base no nome de destino. Cada nome de destino é armazenado o mais geral possível sem colidir com credenciais já armazenadas no gerenciador de credenciais. Um efeito importante do armazenamento de credenciais por nome de destino é que um usuário específico pode ter apenas uma credencial por destino armazenada no gerenciador de credenciais.
Observação
O cabeçalho wincred.h define CredUICmdLinePromptForCredentials 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
| 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] |
| Plataforma de Destino | Windows |
| Cabeçalho | wincred.h |
| Biblioteca | Credui.lib |
| DLL | Credui.dll |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de