PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE callback function (wincrypt.h)

Article
10/13/2021

The PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE function initializes the provider. You must implement this function as part of your custom provider.

Syntax

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE PfnCryptObjectLocatorProviderInitialize;

BOOL PfnCryptObjectLocatorProviderInitialize(
  [in]  PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_FLUSH pfnFlush,
  [in]  LPVOID pContext,
  [out] DWORD *pdwExpectedObjectCount,
  [out] PCRYPT_OBJECT_LOCATOR_PROVIDER_TABLE *ppFuncTable,
  [out] void **ppPluginContext
)
{...}

Parameters

[in] pfnFlush

Pointer to the PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_FLUSH function implementation.

[in] pContext

Pointer to a provider defined object that contains information about the provider and the objects.

[out] pdwExpectedObjectCount

Specifies the number of unique objects that the provider expects to locate. This value tells the caller how much memory to allocate for storing objects. Set this value to zero (0) to specify the default value of 10,000 objects.

[out] ppFuncTable

A CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE structure that contains pointers to the functions implemented by the provider. No pointers in the table can be NULL. The caller does not free this structure. It is expected that the provider will return a table that is not allocated on the heap.

[out] ppPluginContext

Pointer to an optional buffer defined by this provider. The buffer is not modified by the caller. Your provider can use the data to help it determine what actions to perform or to maintain additional information. This value may be set to NULL.

Return value

If the function succeeds, return nonzero (TRUE).

If the function fails, return zero (FALSE) and specify an appropriate error in the SetLastError function. Most errors are passed through Schannel unaltered but this behavior is not guaranteed. Some errors may be mapped to other errors.

Remarks

The PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE function is currently called by only the Secure Channel (Schannel) security service provider (SSP). The Cryptography API (CAPI) will internally call your custom provider if, beginning with Windows 8, you specify the name of the security principal in the pszPrincipal parameter of the AcquireCredentialsHandle function.

When you implement this function, remember to fill the CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE function table with pointers to the following functions implemented by your provider:

You must call CryptRegisterDefaultOIDFunction to register the provider in the Windows registry.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	wincrypt.h