SspiPromptForCredentialsA function (sspi.h)

Article
02/09/2023

Allows a Security Support Provider Interface (SSPI) application to prompt a user to enter credentials.

Syntax

unsigned long SEC_ENTRY SspiPromptForCredentialsA(
  [in]                PCSTR                           pszTargetName,
  [in]                PCREDUI_INFOA                   pUiInfo,
  [in]                unsigned long                   dwAuthError,
  [in]                PCSTR                           pszPackage,
  [in]                PSEC_WINNT_AUTH_IDENTITY_OPAQUE pInputAuthIdentity,
  [out]               PSEC_WINNT_AUTH_IDENTITY_OPAQUE *ppAuthIdentity,
  [in, out, optional] int                             *pfSave,
  [in]                unsigned long                   dwFlags
);

Parameters

[in] pszTargetName

The name of the target to use.

[in] pUiInfo

A pointer to a CREDUI_INFO structure that contains information for customizing the appearance of the dialog box that this function displays.

If the hwndParent member of the CREDUI_INFO structure is not NULL, this function displays a modal dialog box centered on the parent window.

If the hwndParent member of the CREDUI_INFO structure is NULL, the function displays a dialog box centered on the screen.

This function ignores the hbmBanner member of the CREDUI_INFO structure.

[in] dwAuthError

A Windows error code, defined in Winerror.h, that is displayed in the dialog box. If credentials previously collected were not valid, the caller uses this parameter to pass the error message from the API that collected the credentials (for example, Winlogon) to this function. The corresponding error message is formatted and displayed in the dialog box. Set the value of this parameter to zero to display no error message.

[in] pszPackage

The name of the security package to use.

[in] pInputAuthIdentity

An identity structure that is used to populate credential fields in the dialog box. To leave the credential fields empty, set the value of this parameter to NULL.

[out] ppAuthIdentity

An identity structure that represents the credentials this function collects.

When you have finished using this structure, free it by calling the SspiFreeAuthIdentity function.

[in, out, optional] pfSave

A pointer to a Boolean value that, on input, specifies whether the Save check box is selected in the dialog box that this function displays. On output, the value of this parameter specifies whether the Save check box was selected when the user clicked the Submit button in the dialog box. Set this parameter to NULL to ignore the Save check box.

This parameter is ignored if the CREDUIWIN_CHECKBOX flag is not set in the dwFlags parameter.

[in] dwFlags

Flags that determine the behavior of this function. The following flag is currently defined.

Value	Meaning
SSPIPFC_CREDPROV_DO_NOT_SAVE 0x00000001	The value of the pfSave parameter is ignored, and the credentials collected by this function are not saved. Windows 7 and Windows Server 2008 R2: The value of the pfSave parameter is ignored, and the credentials collected by this function are not saved. Only the name of this possible value was SSPIPFC_SAVE_CRED_BY_CALLER.
SSPIPFC_NO_CHECKBOX 0x00000002	The value signifies that password and smart card credential providers will not display the "Remember my credentials" checkbox to the user. The SspiPromptForCredentials function passes this flag value, SSPIPFC_NO_CHECKBOX, in the pvInAuthBuffer parameter of CredUIPromptForWindowsCredentials function.

Return value

If the function succeeds, it returns SEC_E_OK.

If the function fails, it returns a nonzero error code.

Remarks

Note

The sspi.h header defines SspiPromptForCredentials 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 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Target Platform	Windows
Header	sspi.h
Library	Credui.lib
DLL	Credui.dll

Share via