Função CredUICmdLinePromptForCredentialsA (wincred.h)

Artigo
08/27/2023

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 CredUICmdLinePromptForCredentialsA(
  [in]           PCSTR       pszTargetName,
  [in]           PCtxtHandle pContext,
  [in, optional] DWORD       dwAuthError,
  [in, out]      PSTR        UserName,
  [in]           ULONG       ulUserBufferSize,
  [in, out]      PSTR        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.

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, 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.

Nota CREDUI_MAX_PASSWORD_LENGTH não inclui 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
CREDUI_FLAGS_ALWAYS_SHOW_UI	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.
CREDUI_FLAGS_DO_NOT_PERSIST	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.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES	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.
CREDUI_FLAGS_EXPECT_CONFIRMATION	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.
CREDUI_FLAGS_GENERIC_CREDENTIALS	Considere as credenciais inseridas pelo usuário como uma credencial genérica.
CREDUI_FLAGS_INCORRECT_PASSWORD	Ignore silenciosamente esse sinalizador.
CREDUI_FLAGS_PERSIST	Não mostre a mensagem de salvamento, mas salve a credencial como se o usuário respondeu "y".
CREDUI_FLAGS_REQUEST_ADMINISTRATOR	Ignore silenciosamente esse sinalizador.
CREDUI_FLAGS_REQUIRE_CERTIFICATE	Reservado para uso futuro; não passe esse sinalizador.
CREDUI_FLAGS_REQUIRE_SMARTCARD	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.
CREDUI_FLAGS_SERVER_CREDENTIAL	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.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX	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.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS	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.

Retornar valor

O valor retornado é um DWORD e pode ser um dos valores a seguir.

Valor	Descrição
ERROR_INVALID_FLAGS	Essa status é retornada para qualquer uma das combinações de sinalizadores 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 CredUI_INFO apontada não atendeu 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 CredUICmdLinePromptForCredentials e passando o sinalizador CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR	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

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

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. Um computador que é membro de um domínio do Windows não tem um nome de domínio DNS ou um nome de árvore DNS.

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

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