Funzione CredUICmdLinePromptForCredentialsA (wincred.h)

Articolo
03/13/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 una stringa con terminazione Null che contiene 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 una stringa con terminazione Null 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 caratteri ulUserNameMaxChars . 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 per la sicurezza.

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 controllata, stampata o persistente diversa 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 null di terminazione.

Nota CREDUI_MAX_USERNAME_LENGTH non include il carattere null di terminazione.

[in, out] pszPassword

Puntatore a una stringa con terminazione Null 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 di 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 diverso da 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 Null di terminazione.

Nota CREDUI_MAX_PASSWORD_LENGTH non include il carattere null di terminazione.

[in, out] pfSave

Puntatore a un valore BOOL che specifica lo stato iniziale del messaggio Salva 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 una combinazione bit per bit OR 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 possono anche essere passati 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. In questo modo si 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	Prendere in considerazione le credenziali immesse dall'utente come credenziale 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 nel certificato o la stringa corrisponde alla parte a sinistra del segno (@) nell'UPN del certificato. Se è presente 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, se l'autenticazione ha esito negativo. Quando si specifica questo flag, le credenziali con caratteri jolly non verranno corrispondenti. 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 "y", FALSE se l'utente risponde "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 è una DWORD e può essere uno dei valori seguenti.

Valore	Descrizione
ERROR_INVALID_FLAGS	Questo stato viene restituito per tutte le combinazioni di flag non valide.
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 pszUserName, pszPassword e pfSave restituiranno i valori documentati in precedenza.

Commenti

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

Se viene specificato CREDUI_FLAGS_DO_NOT_PERSIST, è necessario specificare pszTargetName oppure specificare uiInfo-pszMessageText> e uiInfo-pszCaption>.

I flag CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS e CREDUI_FLAGS_GENERIC_CREDENTIALS si escludono a vicenda. Se nessuno dei due viene specificato, la credenziale è una credenziale di dominio.

Se CREDUI_FLAGS_GENERIC_CREDENTIALS non è specificato o CREDUI_FLAGS_COMPLETE_USERNAME viene specificato, viene verificato il nome tipizzato. 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 verificato il nome tipizzato. Se il nome tipizzato non è valido, all'utente viene richiesto un nome valido.

Se viene specificato CREDUI_FLAGS_GENERIC_CREDENTIALS 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 viene specificato 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 certificati che non sono certificati di smart card o richiede 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 informazione può essere mancante se le informazioni non si applicano al computer di destinazione. Ad esempio, un computer membro di un gruppo di lavoro non ha un nome di dominio NetBIOS. Un computer membro di un dominio Windows non ha un nome di dominio DNS o un nome di albero DNS.

Le credenziali vengono archiviate in Gestione credenziali in base al nome di destinazione. Ogni nome di destinazione viene archiviato nel modo più generale possibile senza collisarsi con le credenziali già archiviate in Gestione 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wincred.h
Libreria	Credui.lib
DLL	Credui.dll