Функция BCryptOpenAlgorithmProvider (bcrypt.h)

Статья
07/16/2024

Функция BCryptOpenAlgorithmProvider загружает и инициализирует поставщик CNG.

Синтаксис

NTSTATUS BCryptOpenAlgorithmProvider(
  [out] BCRYPT_ALG_HANDLE *phAlgorithm,
  [in]  LPCWSTR           pszAlgId,
  [in]  LPCWSTR           pszImplementation,
  [in]  ULONG             dwFlags
);

Параметры

[out] phAlgorithm

Указатель на переменную BCRYPT_ALG_HANDLE, которая получает дескриптор поставщика CNG. После завершения работы с этим дескриптором отпустите его, передав его в функцию BCryptCloseAlgorithmProvider.

[in] pszAlgId

Указатель на строку Юникода, завершающую значение NULL, которая определяет запрошенный алгоритм шифрования. Это может быть один из стандартных идентификаторов алгоритма CNG или идентификатор другого зарегистрированного алгоритма.

[in] pszImplementation

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

Примечание Если значение параметра pszImplementation равно NULL, CNG пытается открыть каждого зарегистрированного поставщика в порядке приоритета для алгоритма, указанного параметром pszAlgId и возвращает дескриптор первого поставщика, который успешно открыт. В течение всего времени существования дескриптора все криптографические API BCrypt*** будут использовать поставщик, который был успешно открыт.

Windows Server 2008 и Windows Vista: CNG пытается вернуться к поставщику Microsoft CNG.

Ниже приведены предопределенные имена поставщиков.

Ценность	Значение
MS_PRIMITIVE_PROVIDER "Поставщик Microsoft Primitive"	Определяет базовый поставщик Microsoft CNG.
MS_PLATFORM_CRYPTO_PROVIDER L"Поставщик шифрования платформы Майкрософт"	Определяет поставщика хранилища ключей TPM, предоставленного корпорацией Майкрософт.

[in] dwFlags

Флаги, изменяющие поведение функции. Это может быть ноль или сочетание одного или нескольких следующих значений.

Ценность	Значение
BCRYPT_ALG_HANDLE_HMAC_FLAG	Поставщик выполнит алгоритм Hash-Based код проверки подлинности сообщений (HMAC) с указанным хэш-алгоритмом. Этот флаг используется только поставщиками хэш-алгоритмов.
BCRYPT_PROV_DISPATCH	Загружает поставщика в неупакованный пул памяти. Если этот флаг отсутствует, поставщик загружается в пул памяти с страницами. При указании этого флага возвращенный дескриптор не должен быть закрыт до освобождения всех зависимых объектов. Примечание Этот флаг поддерживается только в режиме ядра и позволяет обрабатывать последующие операции с поставщиком на уровне диспетчера. Если поставщик не поддерживает вызов на уровне отправки, он вернет ошибку при открытии с помощью этого флага. Windows Server 2008 и Windows Vista: этот флаг поддерживается только поставщиками алгоритмов Майкрософт и только для алгоритмов хэширования и симметричного ключа алгоритмов шифрования.
BCRYPT_HASH_REUSABLE_FLAG	Создает повторно используемый хэш-объект. Объект можно использовать для новой операции хэширования сразу после вызова BCryptFinishHash. Дополнительные сведения см. в статье Создание хэша с помощьюCNG. Windows Server 2008 R2, Windows 7, Windows Server 2008 и Windows Vista: Этот флаг не поддерживается.

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

Возвращает код состояния, указывающий на успешность или сбой функции.

Возможные коды возврата включают в себя, но не ограничиваются следующими.

Возвращаемый код	Описание
STATUS_SUCCESS	Функция была успешной.
STATUS_NOT_FOUND	Поставщик не найден для указанного идентификатора алгоритма.
STATUS_INVALID_PARAMETER	Один или несколько параметров недопустимы.
STATUS_NO_MEMORY	Произошел сбой выделения памяти.

Замечания

Из-за количества и типа операций, необходимых для поиска, загрузки и инициализации поставщика алгоритмов , функция BCryptOpenAlgorithmProvid er является относительно интенсивной функцией. Из-за этого рекомендуется кэшировать все обработчики алгоритмов, которые будут использоваться более одного раза, а не открывать и закрывать поставщиков алгоритмов.

BCryptOpenAlgorithmProvider можно вызывать из пользовательского режима или режима ядра. Вызывающие вызовы режима ядра должны выполняться в PASSIVE_LEVELIRQL.

Чтобы вызвать эту функцию в режиме ядра, используйте Cng.lib, которая входит в состав пакета средств разработки драйверов (DDK). Windows Server 2008 и Windows Vista: для вызова этой функции в режиме ядра используйте Ksecdd.lib.

Начиная с Windows 10, CNG больше не следует каждому обновлению конфигурации шифрования. Некоторые изменения, такие как добавление нового поставщика по умолчанию или изменение порядка предпочтений поставщиков алгоритмов, могут потребовать перезагрузки. Из-за этого перед вызовом BCryptOpenAlgorithmProvider необходимо перезагрузить с любым новым настроенным поставщиком.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2008 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	bcrypt.h
библиотеки	Bcrypt.lib
DLL	Bcrypt.dll

См. также

BCryptCloseAlgorithmProvider

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