Funzione CredUICmdLinePromptForCredentialsA (wincred.h)

Articolo
11/20/2024

La funzione CredUICmdLinePromptForCredentials richiede e accetta informazioni sulle credenziali da un utente che lavora in un'applicazione della riga di comando (console). Il nome e la password digitati dall'utente vengono restituiti all'applicazione chiamante per la verifica.

Sintassi

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
);

Parametri

[in] pszTargetName

Puntatore a un nullstringa con terminazione contenente il nome della destinazione per le credenziali, in genere un nome del server. Per le connessioni DFS, questa stringa è nel formato NomeServer\ShareName. Il parametro pszTargetName viene usato per identificare le informazioni di destinazione e viene usato per archiviare e recuperare le credenziali.

[in] pContext

Attualmente riservato e deve essere NULL.

[in, optional] dwAuthError

Specifica il motivo per cui è necessaria la richiesta di credenziali. Un chiamante può passare questo parametro di errore di Windows, restituito da un'altra chiamata di autenticazione, per consentire alla finestra di dialogo di contenere determinati errori. Ad esempio, se viene passato il codice di stato scaduto della password, la finestra di dialogo richiede all'utente di modificare la password nell'account.

[in, out] UserName

Puntatore a un nullstringa con terminazione contenente il nome utente delle credenziali. Se viene specificata una stringa diversa da zero per pszUserName, all'utente verrà richiesto solo la password. Nel caso di credenziali diverse da nome utente/password, è possibile passare un formato di marshalling delle credenziali. Questa stringa viene creata chiamando CredMarshalCredential.

Questa funzione scrive il nome fornito dall'utente in questo buffer, copiando un massimo di ulUserNameMaxChars caratteri. La stringa in questo formato può essere convertita nel formato nome utente/password chiamando la funzione CredUIParseUsername . La stringa nel formato di marshalling può essere passata direttamente a un provider di supporto della sicurezza (SSP).

Se il flag di CREDUI_FLAGS_DO_NOT_PERSIST non viene specificato, il valore restituito in questo parametro è di una maschera che non deve essere ispezionata, stampata o persistente diversamente dal passaggio a CredUIParseUsername. I risultati successivi di CredUIParseUsername possono essere passati solo a un'API di autenticazione lato client, ad esempio WNetAddConnection o l'API SSP.

[in] ulUserBufferSize

Numero massimo di caratteri che è possibile copiare in pszUserName incluso il carattere di terminazione null.

Nota CREDUI_MAX_USERNAME_LENGTH non include il carattere di null terminazione.

[in, out] pszPassword

Puntatore a un nullstringa con terminazione contenente la password per le credenziali. Se viene specificata una stringa di lunghezza diversa da zero per pszPassword, il parametro password verrà precompilato con la stringa.

Questa funzione scrive la password fornita dall'utente in questo buffer, copiando un massimo di caratteri ulPasswordMaxChars. Se il flag CREDUI_FLAGS_DO_NOT_PERSIST non viene specificato, il valore restituito in questo parametro è di un modulo che non deve essere esaminato, stampato o salvato in modo permanente oltre a passarlo a una funzione di autenticazione lato client, ad esempio WNetAddConnection o una funzione SSP.

Al termine dell'uso della password, cancellare la password dalla memoria chiamando la funzione secureZeroMemory . Per altre informazioni sulla protezione delle password, vedere Gestione delle password.

[in] ulPasswordBufferSize

Numero massimo di caratteri che è possibile copiare in pszPassword incluso il carattere di terminazione null.

Nota CREDUI_MAX_PASSWORD_LENGTH non include il carattere di null terminazione.

[in, out] pfSave

Puntatore a un bool che specifica lo stato iniziale del messaggio di salvataggio e riceve lo stato del messaggio salva dopo che l'utente ha risposto al prompt dei comandi. Se pfSave non è null e CredUIPromptForCredentials restituisce NO_ERROR, pfSave restituisce lo stato del messaggio Salva . Se viene specificato il flag di CREDUI_FLAGS_PERSIST, il messaggio Salva non viene visualizzato ma viene considerato "y". Se viene specificato il flag CREDUI_FLAGS_DO_NOT_PERSIST e non viene specificato CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX, il messaggio Salva non viene visualizzato ma viene considerato "n".

[in] dwFlags

Valore DWORD che specifica un comportamento speciale per questa funzione. Questo valore può essere unOR bit per bit combinazione di zero o più dei valori seguenti.

Valore	Significato
CREDUI_FLAGS_ALWAYS_SHOW_UI	Visualizzare un'interfaccia utente se le credenziali possono essere restituite da una credenziale esistente in Gestione credenziali. Questo flag è consentito solo se viene specificato anche CREDUI_FLAGS_GENERIC_CREDENTIALS e viene usato solo in combinazione con CREDUI_FLAGS_GENERIC_CREDENTIALS.
CREDUI_FLAGS_DO_NOT_PERSIST	Non visualizzare il messaggio di salvataggio o archiviare le credenziali. CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX può anche essere passato per visualizzare solo il messaggio di salvataggio e restituire il risultato in pfSave.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES	Richiedi nome utente/password. Se viene specificato il parametro pszUserName , il nome utente viene omesso. Se le credenziali sono persistenti, archiviare il nome utente passato con le credenziali.
CREDUI_FLAGS_EXPECT_CONFIRMATION	Specifica che il chiamante chiamerà CredUIConfirmCredentials per determinare se le credenziali restituite sono effettivamente valide. Ciò garantisce che le credenziali non valide non vengano salvate nel gestore delle credenziali. Specificare questo flag a meno che non venga specificato CREDUI_FLAGS_DO_NOT_PERSIST.
CREDUI_FLAGS_GENERIC_CREDENTIALS	Si considerino le credenziali immesse dall'utente con credenziali generica.
CREDUI_FLAGS_INCORRECT_PASSWORD	Ignorare automaticamente questo flag.
CREDUI_FLAGS_PERSIST	Non visualizzare il messaggio di salvataggio, ma salvare le credenziali come se l'utente rispondesse a "y".
CREDUI_FLAGS_REQUEST_ADMINISTRATOR	Ignorare automaticamente questo flag.
CREDUI_FLAGS_REQUIRE_CERTIFICATE	Riservato per uso futuro; non passare questo flag.
CREDUI_FLAGS_REQUIRE_SMARTCARD	Usare una smart card e richiedere un PIN. Se sono disponibili più smart card, selezionare una di esse. Se il parametro pszUserName passa una stringa non vuota, la stringa deve corrispondere all'UPN associato al certificato in una delle smart card. Un UPN corrisponde se la stringa corrisponde all'intero UPN del certificato o la stringa corrisponde alla parte a sinistra del segno (@) nell'UPN del certificato. Se esiste una corrispondenza, viene selezionata la smart card corrispondente.
CREDUI_FLAGS_SERVER_CREDENTIAL	Questo flag è significativo solo nell'individuazione di una credenziale corrispondente per precompilare la finestra di dialogo, in caso di esito negativo dell'autenticazione. Quando si specifica questo flag, le credenziali con caratteri jolly non verranno confrontate. Non ha alcun effetto durante la scrittura di credenziali. CredUI non crea credenziali contenenti caratteri jolly. Tutti gli elementi trovati sono stati creati in modo esplicito dall'utente o creati a livello di codice, come avviene quando viene stabilita una connessione RAS.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX	Visualizzare il messaggio di salvataggio e restituire TRUE nel parametro pfSave out se l'utente risponde a "y", FALSE se l'utente risponde a "n". CREDUI_FLAGS_DO_NOT_PERSIST deve essere specificato per usare questo flag.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS	Le credenziali sono credenziali run-as. Il parametro pszTargetName specifica il nome del comando o del programma in esecuzione. Viene usato solo a scopo di richiesta.

Valore restituito

Il valore restituito è un DWORD e può essere uno dei valori seguenti.

Valore	Descrizione
ERROR_INVALID_FLAGS	Questo stato viene restituito per qualsiasi combinazione di flag non valida.
ERROR_INVALID_PARAMETER	pszTargetName è NULL, la stringa vuota o più lunga di CREDUI_MAX_DOMAIN_LENGTH oppure pUiInfo non è NULL e la struttura CredUI_INFO a cui punta non soddisfa uno dei requisiti seguenti: Il membro cbSize deve essere uno. Se il membro hbmBanner non è null, deve essere di tipo OBJ_BITMAP. Se il membro pszMessageText non è null, non deve essere maggiore di CREDUI_MAX_MESSAGE_LENGTH. Se il membro pszCaptionText non è NULL , non deve essere maggiore di CREDUI_MAX_CAPTION_LENGTH.
ERROR_NO_SUCH_LOGON_SESSION	Non è possibile usare gestione credenziali. In genere, questo errore viene gestito chiamando CredUICmdLinePromptForCredentials e passando il flag di CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR	L'utente ha scelto OK. Le variabili di pszUserName, pszPassworde pfSave restituiranno i valori documentati in precedenza.

Osservazioni

I flag CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE e CREDUI_FLAGS_EXCLUDE_CERTIFICATE si escludono a vicenda.

Se si specifica CREDUI_FLAGS_DO_NOT_PERSIST, è necessario specificare pszTargetName o uiInfo->pszMessageText e uiInfo-> pszCaption.

I flag CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS e CREDUI_FLAGS_GENERIC_CREDENTIALS si escludono a vicenda. Se nessuna delle due credenziali è specificata, la credenziale è una credenziale di dominio.

Se CREDUI_FLAGS_GENERIC_CREDENTIALS non viene specificato o CREDUI_FLAGS_COMPLETE_USERNAME viene specificato, il nome tipizzato è sintassi selezionata. La sintassi selezionata indica che le stesse regole vengono usate come implicite da CredUIParseUserName. Se il nome tipizzato non è valido, all'utente viene richiesto un nome valido. Se manca la parte di dominio del nome tipizzato, ne verrà fornita una in base al nome di destinazione.

Se viene specificato CREDUI_FLAGS_GENERIC_CREDENTIALS e viene specificato anche CREDUI_FLAGS_VALIDATE_USERNAME, viene controllato il nome tipizzato. Se il nome tipizzato non è valido, all'utente viene richiesto un nome valido.

Se CREDUI_FLAGS_GENERIC_CREDENTIALS viene specificato e non viene specificato né CREDUI_FLAGS_COMPLETE_USERNAME né CREDUI_FLAGS_VALIDATE_USERNAME, il nome tipizzato non viene controllato in alcun modo.

Se non vengono impostati né CREDUI_FLAGS_PERSIST né CREDUI_FLAGS_DO_NOT_PERSIST, viene visualizzato il messaggio di salvataggio e controlla se le credenziali vengono salvate o meno.

Se si specifica CREDUI_FLAGS_PROMPT_FOR_SAVE, il parametro pfSave non deve essere NULL.

I flag CREDUI_FLAGS_REQUIRE_SMARTCARD e CREDUI_FLAGS_EXCLUDE_CERTIFICATES si escludono a vicenda. CredUICmdLinePromptForCredentials supporta la richiesta di un certificato di smart card o di credenziali basate su password. Non supporta i certificati che non sono certificati di smart card o che richiedono entrambi in una singola chiamata.

Modalità di chiamata

Il chiamante tenterà di accedere alla risorsa di destinazione, chiamare credui (passando una descrizione della risorsa di destinazione e lo stato di errore), chiamare CredUIParseUserName, accedere di nuovo alla risorsa di destinazione e quindi chiamare CredUIConfirmCredentials.
Il chiamante può richiedere le credenziali senza accedere alle risorse passando CREDUI_FLAGS_DO_NOT_PERSIST.

Informazioni di destinazione

Le informazioni di destinazione sono informazioni sulla posizione della risorsa a cui accedere. Per un elenco di tutti i nomi di destinazione potenziali per una risorsa, chiamare CredGetTargetInfo. CredGetTargetInfo restituisce informazioni memorizzate nella cache dal pacchetto di autenticazione Negotiate, NTLM o Kerberos quando uno di questi pacchetti è stato usato per eseguire l'autenticazione alla destinazione denominata. CredGetTargetInfo restituisce alcuni o tutti i nomi seguenti per la destinazione:

Nome del server NetBIOS del computer
Nome del server DNS del computer
Nome di dominio NetBIOS del dominio a cui appartiene il computer
Nome di dominio DNS del dominio a cui appartiene il computer
Nome dell'albero DNS a cui appartiene il computer
Nome del pacchetto che ha raccolto le informazioni

Qualsiasi parte di queste informazioni può essere mancante se le informazioni non si applicano al computer di destinazione. Ad esempio, un computer membro di un gruppo di lavoro non dispone di un nome di dominio NetBIOS. Un computer membro di un dominio Windows non dispone di un nome di dominio DNS o di un nome di albero DNS.

Le credenziali vengono archiviate nel gestore delle credenziali in base al nome di destinazione. Ogni nome di destinazione viene archiviato il più in generale senza collidere con le credenziali già archiviate nel gestore delle credenziali. Un effetto importante dell'archiviazione delle credenziali in base al nome di destinazione consiste nel fatto che un determinato utente può avere una sola credenziale per destinazione archiviata in Gestione credenziali.

Nota

L'intestazione wincred.h definisce CredUICmdLinePromptForCredentials come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	wincred.h
libreria	Credui.lib
dll	Credui.dll