Функция BCryptGenerateSymmetricKey (bcrypt.h)
Функция BCryptGenerateSymmetricKey создает объект ключа для использования с алгоритмом шифрования симметричного ключа из предоставленного ключа.
Синтаксис
NTSTATUS BCryptGenerateSymmetricKey(
[in, out] BCRYPT_ALG_HANDLE hAlgorithm,
[out] BCRYPT_KEY_HANDLE *phKey,
[out, optional] PUCHAR pbKeyObject,
[in] ULONG cbKeyObject,
[in] PUCHAR pbSecret,
[in] ULONG cbSecret,
[in] ULONG dwFlags
);
Параметры
[in, out] hAlgorithm
Дескриптор поставщика алгоритма, созданного с помощью функции BCryptOpenAlgorithmProvider . Алгоритм, указанный при создании поставщика, должен поддерживать шифрование с симметричным ключом.
[out] phKey
Указатель на BCRYPT_KEY_HANDLE , получающий дескриптор ключа. Этот дескриптор используется в последующих функциях, требующих ключа, например BCryptEncrypt. Этот дескриптор должен быть освобожден, если он больше не нужен, передав его в функцию BCryptDeographyKey .
[out, optional] pbKeyObject
Указатель на буфер, который получает объект ключа. Параметр cbKeyObject содержит размер этого буфера. Требуемый размер этого буфера можно получить, вызвав функцию BCryptGetProperty для получения свойства BCRYPT_OBJECT_LENGTH . Это обеспечит размер объекта ключа для указанного алгоритма.
Эту память можно освободить только после уничтожения дескриптора ключа phKey .
Если значение этого параметра равно NULL , а значение параметра cbKeyObject равно нулю, память для объекта ключа выделяется и освобождается этой функцией. Windows 7: Эта функция управления памятью доступна начиная с Windows 7.
[in] cbKeyObject
Размер буфера pbKeyObject в байтах.
Если значение этого параметра равно нулю, а значение параметра pbKeyObject равно NULL, память для объекта ключа выделяется и освобождается этой функцией. Windows 7: Эта функция управления памятью доступна начиная с Windows 7.
[in] pbSecret
Указатель на буфер, содержащий ключ, из которого создается объект ключа. Параметр cbSecret содержит размер этого буфера. Обычно это хэш пароля или некоторые другие воспроизводимые данные. Если переданные данные превышают размер целевого ключа, данные будут усечены, а избыток будет игнорироваться.
[in] cbSecret
Размер буфера pbSecret в байтах.
[in] dwFlags
Набор флагов, которые изменяют поведение этой функции. В настоящее время флаги не определены, поэтому этот параметр должен быть равен нулю.
Возвращаемое значение
Возвращает код состояния, указывающий на успешное или неудачное выполнение функции.
Возможные коды возврата включают, помимо прочего, следующие.
Код возврата | Описание |
---|---|
|
Функция выполнена успешно. |
|
Размер объекта ключа, указанного параметром cbKeyObject , недостаточно велик для хранения объекта ключа. |
|
Дескриптор алгоритма в параметре hAlgorithm недопустим . |
|
Один или несколько параметров являются недопустимыми. |
Комментарии
В зависимости от того, какие режимы процессора поддерживает поставщик, BCryptGenerateSymmetricKey можно вызывать из пользовательского режима или режима ядра. Вызывающие функции режима ядра могут выполняться в PASSIVE_LEVELIRQL или DISPATCH_LEVEL IRQL. Если текущий уровень IRQL DISPATCH_LEVEL, дескриптор, указанный в параметре hAlgorithm , должен быть открыт с помощью флага BCRYPT_PROV_DISPATCH , а все указатели, передаваемые в функцию BCryptGenerateSymmetricKey , должны ссылаться на непагированную (или заблокированную) память.
Чтобы вызвать эту функцию в режиме ядра, используйте 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 |
См. также раздел
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по