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

Статья
07/16/2024

Функция 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. Этот дескриптор должен быть освобожден, если он больше не нужен, передав его в функцию BCryptDekey.

[in] dwLength

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

Идентификатор алгоритма	Значение
BCRYPT_DH_ALGORITHM	Размер ключа должен быть больше или равен 512 битам, меньше или равно 4096 битам, и должен иметь значение 64.
BCRYPT_DSA_ALGORITHM	До Windows 8 размер ключа должен быть больше или равен 512 битам, меньше или равно 1024 битам, и должен быть кратным из 64. Начиная с Windows 8, размер ключа должен быть больше или равен 512 битам, меньше или равно 3072 битам, и должен быть кратным из 64. Обработка для размеров ключей меньше или равно 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, а все указатели, переданные в функцию BCryptGenerateKeyP air, должны ссылаться на неупакованную (или заблокированную) память.

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

Требования

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

См. также

BCryptDeskkey

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