ICredentialProviderCredential::GetSerialization method (credentialprovider.h)

Article
10/13/2021

Called in response to an attempt to submit this credential to the underlying authentication engine.

Syntax

HRESULT GetSerialization(
  [out] CREDENTIAL_PROVIDER_GET_SERIALIZATION_RESPONSE *pcpgsr,
  [out] CREDENTIAL_PROVIDER_CREDENTIAL_SERIALIZATION   *pcpcs,
  [out] LPWSTR                                         *ppszOptionalStatusText,
  [out] CREDENTIAL_PROVIDER_STATUS_ICON                *pcpsiOptionalStatusIcon
);

Parameters

[out] pcpgsr

Type: CREDENTIAL_PROVIDER_GET_SERIALIZATION_RESPONSE*

Indicates the success or failure of the attempt to serialize credentials.

[out] pcpcs

Type: CREDENTIAL_PROVIDER_CREDENTIAL_SERIALIZATION*

A pointer to the credential. Depending on the result, there may be no valid credential.

[out] ppszOptionalStatusText

Type: LPWSTR*

A pointer to a Unicode string value that will be displayed by the Logon UI after serialization. May be NULL.

[out] pcpsiOptionalStatusIcon

Type: CREDENTIAL_PROVIDER_STATUS_ICON*

A pointer to an icon that will be displayed by the credential after the call to GetSerialization returns. This value can be NULL.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

This method is required.

The CREDENTIAL_PROVIDER_USAGE_SCENARIO indicates what the appropriate response would be when the user attempts to submit credentials. The following table indicates how to respond based on the usage scenario.

CPUS_CHANGE_PASSWORD	No credential serialization occurs in this scenario. In this scenario the credential provider should update the user's private information and return CPGSR_NO_CREDENTIAL_FINISHED as pcpgsr.
CPUS_CREDUI	The credential information should be serialized and delivered to the calling application.
CPUS_LOGON, CPUS_UNLOCK_WORKSTATION	The credential information should be packed into a binary stream and transmitted to Winlogon and eventually LSA.

Credential Provider Best Practices

Credential providers handle extremely sensitive user secrets in order to complete logon and unlock requests. As a best practice, secret information such as passwords and PINs should be handled with the utmost care. Proper techniques for handling secret information within a credential provider are:

Always securely discard secrets. To do this, call SecureZeroMemory before freeing the memory used to hold any secret.
Securely discard secrets promptly after they are used.
Securely discard secrets if they are not used for their intended purpose within an expected amount of time.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	credentialprovider.h

Share via