Funzione CredUIPromptForCredentialsA (wincred.h)
La funzione CredUIPromptForCredentials crea e visualizza una finestra di dialogo configurabile che accetta le informazioni sulle credenziali da un utente.
Le applicazioni destinate a Windows Vista o Windows Server 2008 devono chiamare CredUIPromptForWindowsCredentials anziché questa funzione, per i motivi seguenti:
- CredUIPromptForWindowsCredentials è coerente con l'interfaccia utente di Windows corrente.
- CredUIPromptForWindowsCredentials è più estendibile, consentendo l'integrazione di meccanismi di autenticazione aggiuntivi, ad esempio biometrici e smart card.
- CredUIPromptForWindowsCredentials è conforme alla specifica Common Criteria.
Sintassi
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
);
Parametri
[in, optional] pUiInfo
Puntatore a una struttura CREDUI_INFO che contiene informazioni per personalizzare l'aspetto della finestra di dialogo.
[in] pszTargetName
Puntatore a una stringa con terminazione null contenente il nome della destinazione per le credenziali, in genere un nome del server. Per le connessioni DFS (Distributed File System), questa stringa è del formato ServerName ShareName\. Questo parametro viene usato per identificare le informazioni di destinazione durante l'archiviazione e il recupero delle credenziali.
[in] pContext
Questo parametro è riservato per usi futuri. Deve essere NULL.
[in, optional] dwAuthError
Specifica il motivo per cui è necessaria la finestra di dialogo 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 soddisfare determinati errori. Ad esempio, se viene passato il codice di stato scaduto della password, la finestra di dialogo potrebbe richiedere all'utente di modificare la password nell'account.
[in, out] pszUserName
Puntatore a una stringa con terminazione null contenente il nome utente per le credenziali. Se viene passata una stringa di lunghezza non zero, l'opzione UserName della finestra di dialogo viene precompilata con la stringa. Nel caso di credenziali diverse da UserName/Password, è possibile passare un formato di marshalling delle credenziali. Questa stringa viene creata chiamando CredMarshalCredential.
Questa funzione copia il nome fornito dall'utente in questo buffer, copiando un massimo di caratteri ulUserNameMaxChars . Questo formato può essere convertito in formatopasswordUserName/ usando CredUIParseUsername. Un formato di marshalling può essere passato direttamente a un provider di supporto della sicurezza (SSP).
Se il flag di CREDUI_FLAGS_DO_NOT_PERSIST non è specificato, il valore restituito in questo parametro è di un modulo che non deve essere controllato, stampato o persistente diverso dal passaggio a CredUIParseUsername. I risultati successivi di CredUIParseUsername possono essere passati solo a una funzione di autenticazione lato client, ad esempio WNetAddConnection o a una funzione SSP.
Se non viene specificato alcun dominio o server come parte di questo parametro, il valore del parametro pszTargetName viene usato come dominio per formare una coppia DomainName\UserName . In output, questo parametro riceve una stringa contenente la coppia DomainName UserName\.
[in] ulUserNameBufferSize
Numero massimo di caratteri che possono essere copiati in pszUserName , incluso il carattere null terminante.
[in, out] pszPassword
Puntatore a una stringa con terminazione null contenente la password per le credenziali. Se viene specificata una stringa di lunghezza non zero per pszPassword, l'opzione password della finestra di dialogo verrà precompilata con la stringa.
Questa funzione copia la password fornita dall'utente in questo buffer, copiando un massimo di caratteri ulPasswordMaxChars . Se il flag di CREDUI_FLAGS_DO_NOT_PERSIST non è specificato, il valore restituito in questo parametro è di un modulo che non deve essere controllato, stampato o persistente 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 possono essere copiati in pszPassword , incluso il carattere null terminante.
[in, out] save
Puntatore a un valore BOOL che specifica lo stato iniziale della casella di controllo Salva e riceve lo stato della casella di controllo Salva dopo che l'utente ha risposto alla finestra di dialogo. Se questo valore non è NULL e CredUIPromptForCredentials restituisce NO_ERROR, pfSave restituisce lo stato della casella di controllo Salva quando l'utente ha scelto OK nella finestra di dialogo.
Se viene specificato il flag CREDUI_FLAGS_PERSIST, la casella di controllo Salva non viene visualizzata, ma viene considerata selezionata.
Se il flag CREDUI_FLAGS_DO_NOT_PERSIST viene specificato e CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX non è specificato, la casella di controllo Salva non viene visualizzata, ma viene considerata deselezionata.
Un'applicazione che deve usare CredUI per richiedere all'utente le credenziali, ma non richiede i servizi di gestione delle credenziali forniti dalla gestione credenziali, può usare pfSave per ricevere lo stato della casella di controllo Salva dopo che l'utente chiude la finestra di dialogo. A tale scopo, il chiamante deve specificare CREDUI_FLAGS_DO_NOT_PERSIST e CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX in dwFlags. Quando CREDUI_FLAGS_DO_NOT_PERSIST e CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX vengono impostati, l'applicazione è responsabile dell'esame di *pfSave dopo che la funzione restituisce e se *pfSave è TRUE, l'applicazione deve intraprendere l'azione appropriata per salvare le credenziali utente all'interno delle risorse dell'applicazione.
[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 |
|---|---|
|
Specifica che un'interfaccia utente verrà visualizzata anche se le credenziali possono essere restituite da una credenziale esistente in Gestione credenziali. Questo flag è consentito solo se viene specificato CREDUI_FLAGS_GENERIC_CREDENTIALS. |
|
Popolare la casella combinata con la richiesta di un nome utente. |
|
Non archiviare le credenziali o visualizzare le caselle di controllo. È possibile passare CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX con questo flag per visualizzare solo la casella di controllo Salva e il risultato viene restituito nel parametro di output pfSave . |
|
Popolare la casella combinata solo con nome utente/password. Non visualizzare certificati o smart card nella casella combinata. |
|
Specifica che il chiamante chiamerà CredUIConfirmCredentials dopo aver verificato se le credenziali restituite sono effettivamente valide. Questo meccanismo garantisce che le credenziali non valide non vengano salvate nella gestione credenziali. Specificare questo flag in tutti i casi a meno che non sia specificato CREDUI_FLAGS_DO_NOT_PERSIST. |
|
Prendere in considerazione le credenziali immesse dall'utente per essere credenziali generice. |
|
Notifica all'utente di credenziali insufficienti visualizzando la punta "Accesso non riuscito". |
|
Non consentire all'utente di modificare il nome utente specificato. |
|
Popolare la casella combinata solo con la password. Non consentire l'immissione di un nome utente. |
|
Non visualizzare la casella di controllo Salva , ma le credenziali vengono salvate come se la casella fosse visualizzata e selezionata. |
|
Popolare la casella combinata solo con amministratori locali. Windows XP Home Edition: Questo flag filtra l'account amministratore noto. |
|
Popolare la casella combinata solo con certificati e smart card. Non consentire l'immissione di un nome utente. |
|
Popolare la casella combinata solo con certificati o smart card. Non consentire l'immissione di un nome utente. |
|
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. |
|
Se la casella di controllo è selezionata, visualizzare la casella di controllo Salva e restituire TRUE nel parametro di output pfSave . In caso contrario, restituire FALSE. La casella di controllo usa il valore in pfSave per impostazione predefinita. |
|
Le credenziali sono credenziali "runas". Il parametro TargetName specifica il nome del comando o del programma in esecuzione. Viene usato solo a scopo di richiesta. |
|
Verificare che il nome utente sia valido. |
Valore restituito
Il valore restituito è una DWORD e può essere uno dei valori seguenti.
| Valore | Descrizione |
|---|---|
|
L'utente ha scelto Annulla. I parametri pszUserName e pszPassword non sono stati modificati. |
|
Questo stato viene restituito per qualsiasi configurazione del flag non valida. |
|
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:
|
|
Non è possibile usare Gestione credenziali. In genere, questo errore viene gestito chiamando CredUIPromptForCredentials e passando il flag di CREDUI_FLAGS_DO_NOT_PERSIST. |
|
L'utente ha scelto OK. I parametri pszUserName, pszPassword e pfSave restituiranno i valori documentati in precedenza. |
Commenti
La funzione CredUIPromptForCredentials crea e visualizza una finestra di dialogo modale dell'applicazione. Dopo che la finestra di dialogo viene visualizzata e finché non viene chiusa dall'utente o dall'applicazione, nessun'altra finestra nell'applicazione può diventare attiva.
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.
Un certificato X509 deve avere un valore di utilizzo chiavi avanzato (EKU) di szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.2.2) da visualizzare.
Windows XP: Questo valore EKU non è necessario per visualizzare i certificati X509.
Se CREDUI_FLAGS_GENERIC_CREDENTIALS non è specificato o CREDUI_FLAGS_COMPLETE_USERNAME viene specificato, viene verificato il nome tipizzato. Il controllo della sintassi applica le stesse regole applicate 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 è impostata né CREDUI_FLAGS_PERSIST né CREDUI_FLAGS_DO_NOT_PERSIST, viene visualizzata la casella di controllo Salva e controlla se le credenziali vengono salvate.
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.
- Per le credenziali generice, non è disponibile alcun pacchetto di autenticazione. Pertanto, l'applicazione deve accedere alle credenziali per eseguire l'autenticazione. Richiedere le credenziali, non passando CREDUI_FLAGS_ALWAYS_SHOW_UI prima della prima autenticazione. L'interfaccia utente verrà visualizzata solo se non sono presenti credenziali in Gestione credenziali. In tutti i messaggi successivi dall'interno dell'applicazione, CREDUI_FLAGS_ALWAYS_SHOW_UI verrà passato perché le credenziali nel gestore delle credenziali non sono chiaramente valide per tale risorsa.
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
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. Poiché le credenziali vengono archiviate in base al nome di destinazione, un determinato utente può avere una sola credenziale per ogni destinazione archiviata in Gestione credenziali.
Nota
L'intestazione wincred.h definisce CredUIPromptForCredentials 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 |
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per