GetSerialization

ICredentialProviderCredential::GetSerialization method

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

pcpgsr [out]

Type: CREDENTIAL_PROVIDER_GET_SERIALIZATION_RESPONSE*

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

pcpcs [out]

Type: CREDENTIAL_PROVIDER_CREDENTIAL_SERIALIZATION*

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

ppszOptionalStatusText [out]

Type: LPWSTR*

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

pcpsiOptionalStatusIcon [out]

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_PASSWORDNo 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_CREDUIThe credential information should be serialized and delivered to the calling application.
CPUS_LOGON, CPUS_UNLOCK_WORKSTATIONThe 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

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Credentialprovider.h

IDL

Credentialprovider.idl

 

 

Show:
© 2016 Microsoft