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

Статья
08/22/2023

Функция BCryptGenerateKeyPair создает пустую пару открытого и закрытого ключей. После создания ключа с помощью этой функции можно использовать функцию BCryptSetProperty , чтобы задать ее свойства; однако ключ нельзя использовать, пока не будет вызвана функция BCryptFinalizeKeyPair .

Синтаксис

NTSTATUS BCryptGenerateKeyPair(
  [in, out] BCRYPT_ALG_HANDLE hAlgorithm,
  [out]     BCRYPT_KEY_HANDLE *phKey,
  [in]      ULONG             dwLength,
  [in]      ULONG             dwFlags
);

Параметры

[in, out] hAlgorithm

Дескриптор поставщика алгоритма, поддерживающего подписывание, асимметричное шифрование или соглашение с ключом. Этот дескриптор должен быть создан с помощью функции BCryptOpenAlgorithmProvider .

[out] phKey

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

[in] dwLength

Длина ключа в битах. Поставщики алгоритмов имеют разные ограничения на размер ключа для каждого стандартного асимметричного алгоритма.

Идентификатор алгоритма	Значение
BCRYPT_DH_ALGORITHM	Размер ключа должен быть больше или равен 512 битам, меньше или равен 4096 битам и должен быть кратным 64.
BCRYPT_DSA_ALGORITHM	До Windows 8 размер ключа должен быть больше или равен 512 битам, меньше или равен 1024 битам, а также должен быть кратным 64. Начиная с Windows 8 размер ключа должен быть больше или равен 512 битам, меньше или равен 3072 битам и должен быть кратным 64. Обработка для ключей размером менее 1024 бит или равна 1024 бита соответствует FIPS 186-2. Обработка ключей размером больше 1024 и меньше или равна 3072 соответствует FIPS 186-3.
BCRYPT_ECDH_P256_ALGORITHM	Размер ключа должен быть 256 бит.
BCRYPT_ECDH_P384_ALGORITHM	Размер ключа должен составлять 384 бита.
BCRYPT_ECDH_P521_ALGORITHM	Размер ключа должен быть 521 бит.
BCRYPT_ECDSA_P256_ALGORITHM	Размер ключа должен быть 256 бит.
BCRYPT_ECDSA_P384_ALGORITHM	Размер ключа должен составлять 384 бита.
BCRYPT_ECDSA_P521_ALGORITHM	Размер ключа должен быть 521 бит.
BCRYPT_RSA_ALGORITHM	Размер ключа должен быть больше или равен 512 битам, меньше или равен 16384 битам и должен быть кратным 64.

[in] dwFlags

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

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

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

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

Код возврата	Описание
STATUS_SUCCESS	Функция выполнена успешно.
STATUS_INVALID_HANDLE	Дескриптор алгоритма в параметре hAlgorithm недопустим .
STATUS_INVALID_PARAMETER	Один или несколько параметров недопустимы.
STATUS_NOT_SUPPORTED	Указанный поставщик не поддерживает шифрование асимметричного ключа.

В зависимости от того, какие режимы процессора поддерживает поставщик, BCryptGenerateKeyPair можно вызывать из пользовательского режима или режима ядра. Вызовы режима ядра могут выполняться в PASSIVE_LEVELIRQL или DISPATCH_LEVEL IRQL. Если текущий уровень IRQL DISPATCH_LEVEL, дескриптор, указанный в параметре hAlgorithm , должен быть открыт с помощью флага BCRYPT_PROV_DISPATCH , а все указатели, передаваемые в функцию BCryptGenerateKeyPair , должны ссылаться на непагированную (или заблокированную) память.

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

Требования

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

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

BCryptDe переключение ключей

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