Compartilhar via


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:

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.

Nota CREDUI_MAX_USERNAME_LENGTH não inclui 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.

Nota CREDUI_MAX_PASSWORD_LENGTH não inclui 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
CREDUI_FLAGS_ALWAYS_SHOW_UI
0x00080
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.
CREDUI_FLAGS_COMPLETE_USERNAME
0x00800
Preencha a caixa de combinação com o prompt para um nome de usuário.
CREDUI_FLAGS_DO_NOT_PERSIST
0x00002
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.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES
0x00008
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.
CREDUI_FLAGS_EXPECT_CONFIRMATION
0x20000
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.
CREDUI_FLAGS_GENERIC_CREDENTIALS
0x40000
Considere as credenciais inseridas pelo usuário como credenciais genéricas.
CREDUI_FLAGS_INCORRECT_PASSWORD
0x00001
Notifique o usuário de credenciais insuficientes exibindo a dica de balão "Logon malsucedido".
CREDUI_FLAGS_KEEP_USERNAME
0x100000
Não permita que o usuário altere o nome de usuário fornecido.
CREDUI_FLAGS_PASSWORD_ONLY_OK
0x00200
Preencha a caixa de combinação somente com a senha. Não permita que um nome de usuário seja inserido.
CREDUI_FLAGS_PERSIST
0x01000
Não mostre a caixa Salvar marcar, mas a credencial é salva como se a caixa fosse mostrada e selecionada.
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
0x00004
Preencha a caixa de combinação somente com administradores locais. Windows XP Home Edition: Esse sinalizador filtrará a conta de Administrador conhecida.
CREDUI_FLAGS_REQUIRE_CERTIFICATE
0x00010
Preencha a caixa de combinação apenas com certificados e cartões inteligentes. Não permita que um nome de usuário seja inserido.
CREDUI_FLAGS_REQUIRE_SMARTCARD
0x00100
Preencha a caixa de combinação apenas com certificados ou cartões inteligentes. Não permita que um nome de usuário seja inserido.
CREDUI_FLAGS_SERVER_CREDENTIAL
0x04000
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.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
0x00040
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.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
0x80000
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.
CREDUI_FLAGS_VALIDATE_USERNAME
0x00400
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
ERROR_CANCELLED
O usuário escolheu Cancelar. Os parâmetros pszUserName e pszPassword não foram alterados.
ERROR_INVALID_FLAGS
Esse status é retornado para qualquer uma das configurações de sinalizador que não são válidas.
ERROR_INVALID_PARAMETER
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 membro cbSize deve ser um.
  • Se o membro hbmBanner não for NULL, ele deverá ser do tipo OBJ_BITMAP.
  • Se o membro pszMessageText não for NULL, ele não deverá ser maior que CREDUI_MAX_MESSAGE_LENGTH.
  • Se o membro pszCaptionText não for NULL, ele não deverá ser maior que CREDUI_MAX_CAPTION_LENGTH.
ERROR_NO_SUCH_LOGON_SESSION
O gerenciador de credenciais não pode ser usado. Normalmente, esse erro é tratado chamando CredUIPromptForCredentials e passando o sinalizador CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR
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

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
Qualquer parte dessas informações poderá estar ausente se as informações não se aplicarem ao computador de destino. Por exemplo, um computador que é membro de um grupo de trabalho não tem um nome de domínio NetBIOS.

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

Confira também

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUIPromptForWindowsCredentials

CredUI_INFO

WNetAddConnection