Função CredUIPromptForCredentialsA (wincred.h)
A função
Os aplicativos direcionados 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 do DFS (Sistema de Arquivos Distribuído), essa cadeia de caracteres é do formulário ServerName\do 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 o código de status expirado da senha 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 ulUserNameMaxChars caracteres. Esse formato pode ser convertido em formato UserName/Password usando CredUIParseUsername. Um formato marshaled pode ser passado diretamente para um provedor de suporte de segurança (SSP).
Se o sinalizador de 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 DomainName\UserName. 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 ulPasswordMaxChars caracteres. Se o sinalizador de 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, desmarque 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
Se o sinalizador CREDUI_FLAGS_PERSIST for especificado, a caixa de seleção Salvar 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 de seleção Salvar 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
[in] dwFlags
Um valor DWORD que especifica um comportamento especial para essa função. Esse valor pode ser uma combinação deOR 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 de um nome de usuário. |
|
Não armazene credenciais nem exiba caixas de seleção. Você pode passar CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX com esse sinalizador para exibir somente a caixa de seleção salvar |
|
Preencha a caixa de combinação somente 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 de seleção Salvar, mas a credencial é salva como se a caixa tivesse sido 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. O CredUI não cria credenciais que contêm caracteres curinga. Qualquer um encontrado foi criado explicitamente pelo usuário ou criado programaticamente, como acontece quando uma conexão RAS é feita. |
|
Se a caixa de seleção estiver marcada, mostre a caixa de seleçã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. |
Valor de retorno
O valor retornado é um DWORD
| 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 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, pszPassworde pfSave retornarão os valores documentados anteriormente. |
Observações
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 seja fechada pelo usuário ou aplicativo, nenhuma outra janela no aplicativo poderá se tornar 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 devem 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 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á sintaxe verificada. A verificação de sintaxe aplica as mesmas regras aplicadas por CredUIParseUseUserName. Se o nome digitado não for válido, o usuário será solicitado a fornecer um nome 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 nome 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 de seleção salvar salvar será mostrada e controlará se a credencial é 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 CredUIParseUserName, acessar o recurso de destino novamente e, em seguida, chamar CredUIConfirmCredentials.
- O chamador pode solicitar credenciais sem acessar recursos 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 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 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.
Nota
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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2003 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | wincred.h |
| biblioteca | Credui.lib |
| de DLL |
Credui.dll |
Consulte também
credMarshalCredential