CredUICmdLinePromptForCredentialsW function (wincred.h)
The CredUICmdLinePromptForCredentials function prompts for and accepts credential information from a user working in a command-line (console) application. The name and password typed by the user are passed back to the calling application for verification.
Syntax
CREDUIAPI DWORD CredUICmdLinePromptForCredentialsW(
[in] PCWSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PWSTR UserName,
[in] ULONG ulUserBufferSize,
[in, out] PWSTR pszPassword,
[in] ULONG ulPasswordBufferSize,
[in, out] PBOOL pfSave,
[in] DWORD dwFlags
);
Parameters
[in] pszTargetName
A pointer to a null-terminated string that contains the name of the target for the credentials, typically a server name. For DFS connections, this string is of the form ServerName\ShareName. The pszTargetName parameter is used to identify the target information and is used to store and retrieve the credential.
[in] pContext
Currently reserved and must be NULL.
[in, optional] dwAuthError
Specifies why prompting for credentials is needed. A caller can pass this Windows error parameter, returned by another authentication call, to allow the dialog box to accommodate certain errors. For example, if the password expired status code is passed, the dialog box prompts the user to change the password on the account.
[in, out] UserName
A pointer to a null-terminated string that contains the credential user name. If a nonzero-length string is specified for pszUserName, the user will be prompted only for the password. In the case of credentials other than user name/password, a marshaled format of the credential can be passed in. This string is created by calling CredMarshalCredential.
This function writes the user-supplied name to this buffer, copying a maximum of ulUserNameMaxChars characters. The string in this format can be converted to the user name/password format by calling the CredUIParseUsername function. The string in its marshaled format can be passed directly to a security support provider (SSP).
If the CREDUI_FLAGS_DO_NOT_PERSIST flag is not specified, the value returned in this parameter is of a form that should not be inspected, printed, or persisted other than passing it to CredUIParseUsername. The subsequent results of CredUIParseUsername can be passed only to a client-side authentication API such as WNetAddConnection or the SSP API.
[in] ulUserBufferSize
The maximum number of characters that can be copied to pszUserName including the terminating null character.
[in, out] pszPassword
A pointer to a null-terminated string that contains the password for the credentials. If a nonzero-length string is specified for pszPassword, the password parameter will be prefilled with the string.
This function writes the user-supplied password to this buffer, copying a maximum of ulPasswordMaxChars characters. If the CREDUI_FLAGS_DO_NOT_PERSIST flag is not specified, the value returned in this parameter is of a form that should not be inspected, printed, or persisted other than passing it to a client-side authentication function such as WNetAddConnection or an SSP function.
When you have finished using the password, clear the password from memory by calling the SecureZeroMemory function. For more information about protecting passwords, see Handling Passwords.
[in] ulPasswordBufferSize
The maximum number of characters that can be copied to pszPassword including the terminating null character.
[in, out] pfSave
A pointer to a BOOL that specifies the initial state of the Save message and receives the state of the Save message after the user has responded to the command prompt. If pfSave is not NULL and CredUIPromptForCredentials returns NO_ERROR, pfSave returns the state of the Save message. If the CREDUI_FLAGS_PERSIST flag is specified, the Save message is not displayed but is considered to be "y". If the CREDUI_FLAGS_DO_NOT_PERSIST flag is specified and CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX is not specified, the Save message is not displayed but is considered to be "n".
[in] dwFlags
A DWORD value that specifies special behavior for this function. This value can be a bitwise-OR combination of zero or more of the following values.
Value | Meaning |
---|---|
|
Display a user interface if the credentials can be returned from an existing credential in credential manager. This flag is permitted only if CREDUI_FLAGS_GENERIC_CREDENTIALS is also specified and is used only in conjunction with CREDUI_FLAGS_GENERIC_CREDENTIALS. |
|
Do not display the save message or store credentials.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX can also be passed to display the save message only and return the result in pfSave. |
|
Prompt for user name/password. If the pszUserName parameter is specified, the user name is omitted. If the credential is persisted, store the passed-in user name with the credential. |
|
Specifies that the caller will call CredUIConfirmCredentials to determine whether the returned credentials are actually valid. This ensures that credentials that are not valid are not saved to the credential manager. Specify this flag unless CREDUI_FLAGS_DO_NOT_PERSIST is specified. |
|
Consider the credentials entered by the user a generic credential. |
|
Silently ignore this flag. |
|
Do not show the save message, but save the credential as though the user answered "y". |
|
Silently ignore this flag. |
|
Reserved for future use; do not pass this flag. |
|
Use a smart card and prompt for a PIN. If more than one smart card is available, select one of them. If the pszUserName parameter passes a string that is not empty, the string must match the UPN associated with the certificate on one of the smart cards. A UPN matches if the string matches the whole UPN on the certificate or the string matches the part to the left of the at sign (@) in the UPN of the certificate. If there is a match, the matching smart card is selected. |
|
This flag is meaningful only in locating a matching credential to prefill the dialog box, should authentication fail. When this flag is specified, wildcard credentials will not be matched. It has no effect when writing a credential. CredUI does not create credentials that contain wildcard characters. Any found were either created explicitly by the user or created programmatically, as happens when a RAS connection is made. |
|
Display the save message and return TRUE in the pfSave out parameter if the user answers "y", FALSE if the user answers "n". CREDUI_FLAGS_DO_NOT_PERSIST must be specified to use this flag. |
|
The credential is a run-as credential. The pszTargetName parameter specifies the name of the command or program being run. It is used for prompting purposes only. |
Return value
The return value is a DWORD and can be one of the following values.
Value | Description |
---|---|
|
This status is returned for any of the flag combinations that are not valid. |
|
Either pszTargetName is NULL, the empty string, or longer than CREDUI_MAX_DOMAIN_LENGTH, or pUiInfo is not NULL and the CredUI_INFO structure pointed to did not meet one of the following requirements:
|
|
The credential manager cannot be used. Typically, this error is handled by calling CredUICmdLinePromptForCredentials and passing in the CREDUI_FLAGS_DO_NOT_PERSIST flag. |
|
User chose OK. The pszUserName, pszPassword, and pfSave variables will return the values documented earlier. |
Remarks
The CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE, and CREDUI_FLAGS_EXCLUDE_CERTIFICATE flags are mutually exclusive.
If CREDUI_FLAGS_DO_NOT_PERSIST is specified, either pszTargetName must be specified or uiInfo->pszMessageText and uiInfo->pszCaption must be specified.
The CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS and CREDUI_FLAGS_GENERIC_CREDENTIALS flags are mutually exclusive. If neither is specified, the credential is a domain credential.
If CREDUI_FLAGS_GENERIC_CREDENTIALS is not specified or CREDUI_FLAGS_COMPLETE_USERNAME is specified, the typed name is syntax checked. Syntax checked means that the same rules are used as are implied by CredUIParseUserName. If the typed name is not valid, the user is prompted for a valid one. If the domain portion of the typed name is missing, one will be supplied based on the target name.
If CREDUI_FLAGS_GENERIC_CREDENTIALS is specified and CREDUI_FLAGS_VALIDATE_USERNAME is also specified, the typed name is syntax checked. If the typed name is not valid, the user is prompted for a valid one.
If CREDUI_FLAGS_GENERIC_CREDENTIALS is specified and neither CREDUI_FLAGS_COMPLETE_USERNAME nor CREDUI_FLAGS_VALIDATE_USERNAME is specified, the typed name is not syntax checked in any way.
If neither CREDUI_FLAGS_PERSIST nor CREDUI_FLAGS_DO_NOT_PERSIST are set, the save message is shown, and it controls whether the credential is saved or not.
If CREDUI_FLAGS_PROMPT_FOR_SAVE is specified, the pfSave parameter must not be NULL.
The CREDUI_FLAGS_REQUIRE_SMARTCARD and CREDUI_FLAGS_EXCLUDE_CERTIFICATES flags are mutually exclusive. CredUICmdLinePromptForCredentials supports prompting for a smart card certificate or a password-based credential. It does not support certificates that are not smart card certificates or prompting for both on a single call.
Calling Modes
- The caller will attempt to access the target resource, call credui (passing a description of the target resource and the failure status), call CredUIParseUserName, access the target resource again, and then call CredUIConfirmCredentials.
- The caller can prompt for credentials without accessing any resources by passing CREDUI_FLAGS_DO_NOT_PERSIST.
Target Information is information about the location of the resource to be accessed. For a list of all potential target names for a resource, call CredGetTargetInfo. CredGetTargetInfo returns information that was cached by the Negotiate, NTLM, or Kerberos authentication package when one of those packages was used to authenticate to the named target. CredGetTargetInfo returns some or all of the following names for the target:
- NetBIOS server name of the computer
- DNS server name of the computer
- NetBIOS domain name of the domain the computer belongs to
- DNS domain name of the domain the computer belongs to
- DNS tree name of the tree the computer belongs to
- Name of the package that collected the information
Credentials are stored in the credential manager based on target name. Each target name is stored as generally as possible without colliding with credentials already stored in the credential manager. An important effect of storing credentials by target name is that a particular user can have only one credential per target stored in the credential manager.
Note
The wincred.h header defines CredUICmdLinePromptForCredentials as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows XP [desktop apps only] |
Minimum supported server | Windows Server 2003 [desktop apps only] |
Target Platform | Windows |
Header | wincred.h |
Library | Credui.lib |
DLL | Credui.dll |