Funzione CredUIPromptForCredentialsA (wincred.h)
La funzione CredUIPromptForCredentials crea e visualizza una finestra di dialogo configurabile che accetta le informazioni sulle credenziali di 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 corrente di Windows.
- CredUIPromptForWindowsCredentials è più estendibile, consentendo l'integrazione di meccanismi di autenticazione aggiuntivi, ad esempio biometria 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 è nel formato NomeServer\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 un uso futuro. 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 contenere determinati errori. Ad esempio, se viene passato il codice di stato della password scaduto, 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 diversa da 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 con marshalling delle credenziali. Questa stringa viene creata chiamando CredMarshalCredential.
Questa funzione copia il nome fornito dall'utente in questo buffer, copiando un massimo di ulUserNameMaxChars caratteri. Questo formato può essere convertito in formato UserName/Password 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 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 una funzione di autenticazione lato client, ad esempio WNetAddConnection o 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 NomeDominio\NomeUtente. Nell'output, questo parametro riceve una stringa che contiene che DomainName\coppia userName.
[in] ulUserNameBufferSize
Numero massimo di caratteri che è possibile copiare in pszUserName incluso 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, 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 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
[in] ulPasswordBufferSize
Numero massimo di caratteri che è possibile copiare in pszPassword incluso il carattere Null di terminazione.
[in, out] save
Puntatore a un
Se viene specificato il flag CREDUI_FLAGS_PERSIST, la casella di controllo Salva non viene visualizzata, ma viene considerata selezionata.
Se viene specificato il flag CREDUI_FLAGS_DO_NOT_PERSIST e non viene specificato CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX, la casella di controllo Salva non viene visualizzata, ma viene considerata deselezionata.
Un'applicazione che deve usare CredUI per richiedere le credenziali all'utente, ma non richiede i servizi di gestione delle credenziali forniti dal gestore delle credenziali, può usare
[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 |
|---|---|
|
Specifica che verrà visualizzata un'interfaccia utente 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 il prompt 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 |
|
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 nel gestore delle credenziali. Specificare questo flag in tutti i casi, a meno che non venga specificato CREDUI_FLAGS_DO_NOT_PERSIST. |
|
Considerare le credenziali immesse dall'utente come credenziali generica. |
|
Notifica all'utente di credenziali insufficienti visualizzando il suggerimento per l'area "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 |
|
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, 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. |
|
Se la casella di controllo è selezionata, visualizzare la casella di controllo salva |
|
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 è un DWORD
| 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. |
|
|
|
Non è possibile usare gestione credenziali. In genere, questo errore viene gestito chiamando CredUIPromptForCredentials e passando il flag CREDUI_FLAGS_DO_NOT_PERSIST. |
|
L'utente ha scelto OK. I parametri di pszUserName, pszPassworde pfSave restituiranno i valori documentati in precedenza. |
Osservazioni
La funzione credUIPromptForCredentials
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.
Per visualizzare un certificato X509 deve essere presente un valore di
Windows XP: Questo valore EKU non è necessario per visualizzare i certificati X509.
Se CREDUI_FLAGS_GENERIC_CREDENTIALS non viene specificato o CREDUI_FLAGS_COMPLETE_USERNAME viene specificato, il nome tipizzato è sintassi selezionata. 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 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 viene impostata alcuna 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 in Gestione 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 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. 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 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 |