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

Статья
03/09/2023

Функция 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 пытается вернуться к поставщику CNG Майкрософт.

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

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

[in] dwFlags

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

Значение	Значение
BCRYPT_ALG_HANDLE_HMAC_FLAG	Поставщик будет выполнять алгоритм кода проверки подлинности сообщений на основе хэша (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	Произошел сбой выделения памяти.

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

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

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

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

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	bcrypt.h
Библиотека	Bcrypt.lib
DLL	Bcrypt.dll

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

BCryptCloseAlgorithmProvider