PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET回调函数 (wincrypt.h)

项目
03/03/2024

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET回调函数检索对象。必须将此函数作为自定义提供程序的一部分来实现。当前只有安全通道 (Schannel) 安全包调用此函数。

语法

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
)
{...}

参数

[in, optional] pPluginContext

指向此提供程序定义并由 PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE 函数返回的可选缓冲区的指针。调用方不会修改缓冲区。提供程序可以使用数据来帮助其确定要执行的操作或维护其他信息。

[in, optional] pIdentifier

指向包含对象标识符的CRYPTOAPI_BLOB 结构的指针。首次调用此函数时，此值应始终为 NULL 。

[in] dwNameType

pNameBlob 参数的名称格式。下面列出了可能的值。此函数的实现必须能够处理由 Schannel 传入 的CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE。

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

指向 CRYPTOAPI_BLOB 结构的指针，该结构包含调用应用程序用于唯一标识对象的名称。提供程序使用此名称来查找请求的对象。 Schannel 当前提交 DNS (域名系统) 以 UTF8 编码的主机名，IDN 名称从 punycode 转换。

[out] ppbContent

指向包含要返回的对象的字节数组的指针。

[out] pcbContent

ppbContent 参数指向的对象的大小（以字节为单位）。

[out] ppwszPassword

以 Null 结尾的 Unicode 字符串，其中包含用于加密对象的密码（如果有）。如果对象是 PFX) 文件 (个人信息交换，则密码通常用于执行加密。如果不需要密码，此值可以为 NULL 。

[out] ppIdentifier

接收指向可选标识符的指针的地址，该标识符可在后续调用此函数期间用于更改通知。有关详细信息，请参阅“备注”。如果提供程序将此值设置为 NULL，则 Schannel 在内部使用 pNameBlob 参数值。

返回值

如果函数成功，则返回非零 (TRUE) 。

如果函数失败，则返回零 (FALSE) 并在 SetLastError 函数中指定相应的错误。大多数错误都是通过 Schannel 未更改传递的，但无法保证此行为。某些错误可能映射到其他错误。

如果无法返回给定 DNS 名称 (pNameBlob) 或标识符 (pIdentifier) 的对象，则返回 FALSE 并在 SetLastError 函数中指定CRYPT_E_OBJECT_LOCATOR_OBJECT_NOT_FOUND。

注解

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET回调函数当前仅由安全通道 (Schannel) 安全包调用。可以返回封装下列项之一的对象：

(PFX) 字节数组交换个人信息
证书存储。
泛型 BLOB。 Schannel 当前不支持此操作。

首次调用此函数时，Schannel 在 pNameBlob 参数中提交 DNS 主机名，以指定对象的目标主机。提供程序必须处理名称 (匹配通配符、生成文件路径等) 来确定要查找的对象。

由于许多主机名可以映射到一个对象，因此提供程序可以使用 ppIdentifier 参数返回内部定义的标识符，该标识符可由加密 API (CAPI) 函数的后续调用中使用。然后，提供程序可以使用标识符来帮助查找相应的对象。

要求

要求	值
最低受支持的客户端	Windows 8 [仅限桌面应用]
最低受支持的服务器	Windows Server 2012 [仅限桌面应用]
目标平台	Windows
标头	wincrypt.h

另请参阅

CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE

通过