Função CredUIPromptForCredentialsA (wincred.h)
A função CredUIPromptForCredentials cria e exibe uma caixa de diálogo configurável que aceita informações de credenciais de um usuário.
Os aplicativos destinados ao Windows Vista ou ao Windows Server 2008 devem chamar CredUIPromptForWindowsCredentials em vez dessa função, pelos seguintes motivos:
- CredUIPromptForWindowsCredentials é consistente com a interface do usuário atual do Windows.
- CredUIPromptForWindowsCredentials é mais extensível, permitindo a integração de mecanismos de autenticação adicionais, como biometria e cartões inteligentes.
- CredUIPromptForWindowsCredentials está em conformidade com a especificação Common Criteria.
Sintaxe
CREDUIAPI DWORD CredUIPromptForCredentialsA(
[in, optional] PCREDUI_INFOA pUiInfo,
[in] PCSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PSTR pszUserName,
[in] ULONG ulUserNameBufferSize,
[in, out] PSTR pszPassword,
[in] ULONG ulPasswordBufferSize,
[in, out] BOOL *save,
[in] DWORD dwFlags
);
Parâmetros
[in, optional] pUiInfo
Um ponteiro para uma estrutura CREDUI_INFO que contém informações para personalizar a aparência da caixa de diálogo.
[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 (sistema de arquivos distribuído), essa cadeia de caracteres é do formato ServerName\ShareName. Esse parâmetro é usado para identificar informações de destino ao armazenar e recuperar credenciais.
[in] pContext
Esse parâmetro é reservado para uso futuro. Deve ser NULL.
[in, optional] dwAuthError
Especifica por que a caixa de diálogo de credencial é 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 poderá solicitar que o usuário altere a senha na conta.
[in, out] pszUserName
Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome de usuário para as credenciais. Se uma cadeia de caracteres de comprimento diferente de zero for passada, a opção UserName da caixa de diálogo será preenchida previamente com a cadeia de caracteres. No caso de credenciais diferentes de UserName/Password, um formato marshaled da credencial pode ser passado. Essa cadeia de caracteres é criada chamando CredMarshalCredential.
Essa função copia o nome fornecido pelo usuário para esse buffer, copiando um máximo de caracteres ulUserNameMaxChars . Esse formato pode ser convertido em formatode Senha de Nome de Usuário/ usando CredUIParseUsername. Um formato marshaled pode ser passado 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 função de autenticação do lado do cliente, como WNetAddConnection ou uma função SSP.
Se nenhum domínio ou servidor for especificado como parte desse parâmetro, o valor do parâmetro pszTargetName será usado como o domínio para formar um par DomainNameUserName\. Na saída, esse parâmetro recebe uma cadeia de caracteres que contém esse par DomainName\UserName .
[in] ulUserNameBufferSize
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, a opção de senha da caixa de diálogo será preenchida previamente com a cadeia de caracteres.
Essa função copia a senha fornecida pelo usuário para esse 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] save
Um ponteiro para um BOOL que especifica o estado inicial da caixa Salvar marcar e recebe o estado da caixa Salvar marcar depois que o usuário respondeu à caixa de diálogo. Se esse valor não for NULL e CredUIPromptForCredentials retornar NO_ERROR, pfSave retornará o estado da caixa Salvar marcar quando o usuário escolheu OK na caixa de diálogo.
Se o sinalizador CREDUI_FLAGS_PERSIST for especificado, a caixa Salvar marcar não será exibida, mas será considerada selecionada.
Se o sinalizador CREDUI_FLAGS_DO_NOT_PERSIST for especificado e CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX não for especificado, a caixa Salvar marcar não será exibida, mas será considerada desmarcada.
Um aplicativo que precisa usar CredUI para solicitar credenciais ao usuário, mas não precisa dos serviços de gerenciamento de credenciais fornecidos pelo gerenciador de credenciais, pode usar pfSave para receber o estado da caixa Salvar marcar depois que o usuário fecha a caixa de diálogo. Para fazer isso, o chamador deve especificar CREDUI_FLAGS_DO_NOT_PERSIST e CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX em dwFlags. Quando CREDUI_FLAGS_DO_NOT_PERSIST e CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX são definidos, o aplicativo é responsável por examinar *pfSave após o retorno da função e, se *pfSave for TRUE, o aplicativo deverá tomar a ação apropriada para salvar as credenciais do usuário dentro dos recursos do aplicativo.
[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 |
|---|---|
|
Especifica que uma interface do usuário será mostrada mesmo 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. |
|
Preencha a caixa de combinação com o prompt para um nome de usuário. |
|
Não armazene credenciais nem exiba marcar caixas. Você pode passar CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX com esse sinalizador para exibir somente a caixa Salvar marcar e o resultado é retornado no parâmetro de saída pfSave. |
|
Preencha a caixa de combinação apenas com nome de usuário/senha. Não exiba certificados ou cartões inteligentes na caixa de combinação. |
|
Especifica que o chamador chamará CredUIConfirmCredentials depois de verificar se as credenciais retornadas são realmente válidas. Esse mecanismo garante que as credenciais que não são válidas não sejam salvas no gerenciador de credenciais. Especifique esse sinalizador em todos os casos, a menos que CREDUI_FLAGS_DO_NOT_PERSIST seja especificado. |
|
Considere as credenciais inseridas pelo usuário como credenciais genéricas. |
|
Notifique o usuário de credenciais insuficientes exibindo a dica de balão "Logon malsucedido". |
|
Não permita que o usuário altere o nome de usuário fornecido. |
|
Preencha a caixa de combinação somente com a senha. Não permita que um nome de usuário seja inserido. |
|
Não mostre a caixa Salvar marcar, mas a credencial é salva como se a caixa fosse mostrada e selecionada. |
|
Preencha a caixa de combinação somente com administradores locais. Windows XP Home Edition: Esse sinalizador filtrará a conta de Administrador conhecida. |
|
Preencha a caixa de combinação apenas com certificados e cartões inteligentes. Não permita que um nome de usuário seja inserido. |
|
Preencha a caixa de combinação apenas com certificados ou cartões inteligentes. Não permita que um nome de usuário seja inserido. |
|
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 contêm caracteres curinga. Qualquer encontrado foi criado explicitamente pelo usuário ou criado programaticamente, como acontece quando uma conexão RAS é feita. |
|
Se a caixa marcar estiver selecionada, mostre a caixa Salvar marcar e retorne TRUE no parâmetro de saída pfSave, caso contrário, retornará FALSE. A caixa de seleção usa o valor em pfSave por padrão. |
|
A credencial é uma credencial "runas". O parâmetro TargetName especifica o nome do comando ou programa que está sendo executado. Ele é usado apenas para fins de solicitação. |
|
Verifique se o nome de usuário é válido. |
Retornar valor
O valor retornado é um DWORD e pode ser um dos valores a seguir.
| Valor | Descrição |
|---|---|
|
O usuário escolheu Cancelar. Os parâmetros pszUserName e pszPassword não foram alterados. |
|
Esse status é retornado para qualquer uma das configurações de sinalizador 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 de CredUI_INFO apontada não atendia a um dos seguintes requisitos:
|
|
O gerenciador de credenciais não pode ser usado. Normalmente, esse erro é tratado chamando CredUIPromptForCredentials e passando o sinalizador CREDUI_FLAGS_DO_NOT_PERSIST. |
|
O usuário escolheu OK. Os parâmetros pszUserName, pszPassword e pfSave retornarão os valores documentados anteriormente. |
Comentários
A função CredUIPromptForCredentials cria e exibe uma caixa de diálogo modal do aplicativo. Depois que a caixa de diálogo for exibida e até que ela seja fechada pelo usuário ou aplicativo, nenhuma outra janela no aplicativo poderá ficar ativa.
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 dos dois for especificado, a credencial será uma credencial de domínio.
Um certificado X509 deve ter um valor de EKU ( uso aprimorado de chave ) de szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.2.2) a ser exibido.
Windows XP: Esse valor de EKU não é necessário para exibir certificados X509.
Se CREDUI_FLAGS_GENERIC_CREDENTIALS não for especificado ou CREDUI_FLAGS_COMPLETE_USERNAME for especificado, o nome digitado será verificado. A verificação de sintaxe aplica as mesmas regras aplicadas 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 estiver definido, a caixa Salvar marcar será mostrada e controlará se a credencial será salva.
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 CredUIParseUseUserName, 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.
- Para credenciais genéricas, não há nenhum pacote de autenticação. Portanto, o aplicativo precisa acessar a credencial para fazer a autenticação. Solicite credenciais, não passando CREDUI_FLAGS_ALWAYS_SHOW_UI antes da primeira autenticação. A interface do usuário será exibida somente se não houver nenhuma credencial no gerenciador de credenciais. Em todas as mensagens subsequentes de dentro do aplicativo, CREDUI_FLAGS_ALWAYS_SHOW_UI será passado porque a credencial no gerenciador de credenciais claramente não é válida para esse recurso.
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 à 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. Como as credenciais são armazenadas pelo nome de destino, um usuário específico só pode ter uma credencial por destino armazenada no gerenciador de credenciais.
Observação
O cabeçalho wincred.h define CredUIPromptForCredentials 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
| 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] |
| Plataforma de Destino | Windows |
| Cabeçalho | wincred.h |
| Biblioteca | Credui.lib |
| DLL | Credui.dll |