Funzione CredUIPromptForCredentialsA (wincred.h)

  • Articolo

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:

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.

Nota CREDUI_MAX_USERNAME_LENGTH non include 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.

Nota CREDUI_MAX_PASSWORD_LENGTH non include 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
CREDUI_FLAGS_ALWAYS_SHOW_UI
0x00080
 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.
CREDUI_FLAGS_COMPLETE_USERNAME
0x00800
 Popolare la casella combinata con la richiesta di un nome utente.
CREDUI_FLAGS_DO_NOT_PERSIST
0x00002
 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 .
CREDUI_FLAGS_EXCLUDE_CERTIFICATES
0x00008
 Popolare la casella combinata solo con nome utente/password. Non visualizzare certificati o smart card nella casella combinata.
CREDUI_FLAGS_EXPECT_CONFIRMATION
0x20000
 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.
CREDUI_FLAGS_GENERIC_CREDENTIALS
0x40000
 Prendere in considerazione le credenziali immesse dall'utente per essere credenziali generice.
CREDUI_FLAGS_INCORRECT_PASSWORD
0x00001
 Notifica all'utente di credenziali insufficienti visualizzando la punta "Accesso non riuscito".
CREDUI_FLAGS_KEEP_USERNAME
0x100000
 Non consentire all'utente di modificare il nome utente specificato.
CREDUI_FLAGS_PASSWORD_ONLY_OK
0x00200
 Popolare la casella combinata solo con la password. Non consentire l'immissione di un nome utente.
CREDUI_FLAGS_PERSIST
0x01000
 Non visualizzare la casella di controllo Salva , ma le credenziali vengono salvate come se la casella fosse visualizzata e selezionata.
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
0x00004
 Popolare la casella combinata solo con amministratori locali. Windows XP Home Edition: Questo flag filtra l'account amministratore noto.
CREDUI_FLAGS_REQUIRE_CERTIFICATE
0x00010
 Popolare la casella combinata solo con certificati e smart card. Non consentire l'immissione di un nome utente.
CREDUI_FLAGS_REQUIRE_SMARTCARD
0x00100
 Popolare la casella combinata solo con certificati o smart card. Non consentire l'immissione di un nome utente.
CREDUI_FLAGS_SERVER_CREDENTIAL
0x04000
 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
0x00040
 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.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
0x80000
 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.
CREDUI_FLAGS_VALIDATE_USERNAME
0x00400
 Verificare che il nome utente sia valido.

Valore restituito

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

Valore Descrizione
ERROR_CANCELLED
 L'utente ha scelto Annulla. I parametri pszUserName e pszPassword non sono stati modificati.
ERROR_INVALID_FLAGS
 Questo stato viene restituito per qualsiasi configurazione del 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 CredUIPromptForCredentials e passando il flag di CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR
 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.
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.

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

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUIPromptForWindowsCredentials

CredUI_INFO

WNetAddConnection