PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET callback function (wincrypt.h)

Article
10/13/2021

The PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET callback function retrieves an object. You must implement this function as part of your custom provider. This function is currently called by only the Secure Channel (Schannel) security package.

Syntax

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET PfnCryptObjectLocatorProviderGet;

BOOL PfnCryptObjectLocatorProviderGet(
  [in, optional] LPVOID pPluginContext,
  [in, optional] PCRYPT_DATA_BLOB pIdentifier,
  [in]           DWORD dwNameType,
  [in]           PCERT_NAME_BLOB pNameBlob,
  [out]          PBYTE *ppbContent,
  [out]          DWORD *pcbContent,
  [out]          PCWSTR *ppwszPassword,
  [out]          PCRYPT_DATA_BLOB *ppIdentifier
)
{...}

Parameters

[in, optional] pPluginContext

Pointer to an optional buffer defined by this provider and returned by the PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE function. 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.

[in, optional] pIdentifier

Pointer to a CRYPTOAPI_BLOB structure that contains the object identifier. This value should always be NULL on the first call to this function.

[in] dwNameType

The name format of the pNameBlob parameter. Possible values are listed below. The implementation of this function must be able to process CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE, which is passed in by Schannel.

CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE (1 (0x1))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_NAME_TYPE (32 (0x20))

CRYPT_OBJECT_LOCATOR_FIRST_RESERVED_USER_NAME_TYPE (33 (0x21))

CRYPT_OBJECT_LOCATOR_LAST_RESERVED_USER_NAME_TYPE (0x0000FFFF)

[in] pNameBlob

Pointer to a CRYPTOAPI_BLOB structure that contains the name the calling application is using to uniquely identify the object. Your provider uses this name to locate the requested object. Schannel currently submits a DNS (domain name system) host name encoded in UTF8 with IDN names converted from punycode.

[out] ppbContent

Pointer to a byte array that contains the object to be returned.

[out] pcbContent

The size, in bytes, of the object pointed to by the ppbContent parameter.

[out] ppwszPassword

Null-terminated Unicode string that contains the password, if any, used to encrypt the object. If the object is a personal information exchange (PFX) file, a password will typically be used to perform encryption. This value can be NULL if no password is required.

[out] ppIdentifier

Address that receives a pointer to an optional identifier that can be used during subsequent calls to this function and for change notifications. For more information, see Remarks. If your provider sets this value to NULL, Schannel internally uses the pNameBlob parameter value.

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.

If an object cannot be returned for a given DNS name (pNameBlob) or identifier (pIdentifier), return FALSE and specify CRYPT_E_OBJECT_LOCATOR_OBJECT_NOT_FOUND in the SetLastError function.

Remarks

The PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET callback function is currently called by only the Secure Channel (Schannel) security package. You can return an object that encapsulates one of the following:

A personal information exchange (PFX) byte array
A certificate store.
A generic BLOB. This is not currently supported by Schannel.

When this function is first called, Schannel submits a DNS host name in the pNameBlob argument to specify the host for which the object is intended. Your provider must process the name (match wild cards, build a file path, and so on) to determine what object to find.

Because many host names can be mapped to one object, your provider can use the ppIdentifier parameter to return an internally defined identifier that can be used in subsequent calls by the cryptography API (CAPI) functions to the provider. The provider can then use the identifier to assist in finding the appropriate object.

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

Share via