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

[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

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

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

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

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

Замечания

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

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

Требования

См. также

BCryptDeskkey