функция обратного вызова PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET (wincrypt.h)

Статья
03/13/2024

Функция обратного вызова PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET извлекает объект . Эту функцию необходимо реализовать как часть пользовательского поставщика. В настоящее время эта функция вызывается только пакетом безопасности Secure Channel (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 . Возможные значения перечислены ниже. Реализация этой функции должна иметь возможность обрабатывать CRYPT_OBJECT_LOCATOR_SPN_NAME_TYPE, которые передаются 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

Указатель на структуру CRYPTOAPI_BLOB , содержащую имя, используемое вызывающим приложением для уникальной идентификации объекта. Поставщик использует это имя для поиска запрошенного объекта. В настоящее время Schannel отправляет имя узла DNS (системы доменных имен), закодированное в UTF8, с именами IDN, преобразованными из punycode.

[out] ppbContent

Указатель на массив байтов, содержащий возвращаемый объект.

[out] pcbContent

Размер объекта в байтах, на который указывает параметр ppbContent .

[out] ppwszPassword

Строка Юникода, завершающаяся null, которая содержит пароль , если таковой имеется, используемый для шифрования объекта. Если объект является PFX-файлом, для шифрования обычно используется пароль. Это значение может иметь значение NULL , если пароль не требуется.

[out] ppIdentifier

Адрес, получающий указатель на необязательный идентификатор, который можно использовать во время последующих вызовов этой функции и для уведомлений об изменениях. Дополнительные сведения см. в подразделе "Примечания". Если поставщик задает для этого значения значение NULL, Schannel внутренне использует значение параметра pNameBlob .

Возвращаемое значение

Если функция выполнена успешно, возвращается ненулевое значение (TRUE).

Если функция завершается сбоем, верните ноль (FALSE) и укажите соответствующую ошибку в функции SetLastError . Большинство ошибок передаются через Schannel без изменения, но такое поведение не гарантируется. Некоторые ошибки могут быть сопоставлены с другими.

Если объект не может быть возвращен для заданного DNS-имени (pNameBlob) или идентификатора (pIdentifier), верните значение FALSE и укажите CRYPT_E_OBJECT_LOCATOR_OBJECT_NOT_FOUND в функции SetLastError .

Функция обратного вызова PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_GET в настоящее время вызывается только пакетом безопасности Secure Channel (Schannel). Можно вернуть объект, который инкапсулирует одно из следующих элементов:

Массив байтов обмена личной информацией (PFX)
Хранилище сертификатов.
Универсальный BLOB-объект. В настоящее время это не поддерживается Schannel.

При первом вызове этой функции Schannel отправляет имя узла DNS в аргументе pNameBlob , чтобы указать узел, для которого предназначен объект . Поставщик должен обработать имя (сопоставить подстановочные знаки, создать путь к файлу и т. д.), чтобы определить, какой объект следует найти.

Так как с одним объектом можно сопоставить множество имен узлов, поставщик может использовать параметр ppIdentifier для возврата внутреннего идентификатора, который может использоваться в последующих вызовах функций API шифрования (CAPI) к поставщику. Затем поставщик может использовать идентификатор для оказания помощи в поиске соответствующего объекта.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8 [только классические приложения]
Минимальная версия сервера	Windows Server 2012 [только классические приложения]
Целевая платформа	Windows
Header	wincrypt.h

См. также раздел

CRYPT_OBJECT_LOCATOR_PROVIDER_TABLE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_INITIALIZE

PFN_CRYPT_OBJECT_LOCATOR_PROVIDER_RELEASE

Поделиться через