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

Статья
03/14/2023

Функция BCryptEncrypt шифрует блок данных.

Синтаксис

NTSTATUS BCryptEncrypt(
  [in, out]           BCRYPT_KEY_HANDLE hKey,
  [in]                PUCHAR            pbInput,
  [in]                ULONG             cbInput,
  [in, optional]      VOID              *pPaddingInfo,
  [in, out, optional] PUCHAR            pbIV,
  [in]                ULONG             cbIV,
  [out, optional]     PUCHAR            pbOutput,
  [in]                ULONG             cbOutput,
  [out]               ULONG             *pcbResult,
  [in]                ULONG             dwFlags
);

Параметры

[in, out] hKey

Дескриптор ключа, используемого для шифрования данных. Этот дескриптор получен из одной из функций создания ключа, таких как BCryptGenerateSymmetricKey, BCryptGenerateKeyPair или BCryptImportKey.

[in] pbInput

Адрес буфера, содержащего зашифрованный открытый текст. Параметр cbInput содержит размер открытого текста для шифрования. Дополнительные сведения см. в подразделе "Примечания".

[in] cbInput

Число байтов в буфере pbInput для шифрования.

[in, optional] pPaddingInfo

Указатель на структуру, содержащую сведения о заполнении. Этот параметр используется только с асимметричными ключами и режимами шифрования, прошедшими проверку подлинности. Если используется режим шифрования с проверкой подлинности, этот параметр должен указывать на BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO структуру. Если используются асимметричные ключи, тип структуры, на которую указывает этот параметр, определяется значением параметра dwFlags . В противном случае для параметра должно быть задано значение NULL.

[in, out, optional] pbIV

Адрес буфера, содержащего вектор инициализации (IV), используемый во время шифрования. Параметр cbIV содержит размер этого буфера. Эта функция изменит содержимое этого буфера. Если вам потребуется повторно использовать iv позже, убедитесь, что вы сделали копию этого буфера перед вызовом этой функции.

Этот параметр является необязательным и может иметь значение NULL , если инициализация не используется.

Требуемый размер iv можно получить, вызвав функцию BCryptGetProperty , чтобы получить свойство BCRYPT_BLOCK_LENGTH . Это обеспечит размер блока для алгоритма, который также равен размеру инициализации.

[in] cbIV

Размер буфера pbIV в байтах.

[out, optional] pbOutput

Адрес буфера, который получает зашифрованный текст , созданный этой функцией. Параметр cbOutput содержит размер этого буфера. Дополнительные сведения см. в подразделе "Примечания".

Если этот параметр имеет значение NULL, функция BCryptEncrypt вычисляет размер, необходимый для зашифрованного текста данных, переданных в параметре pbInput . В этом случае расположение, на которое указывает параметр pcbResult , содержит этот размер, а функция возвращает STATUS_SUCCESS. Параметр pPaddingInfo не изменяется.

Если значения параметров pbOutput и pbInput имеют значение NULL, возвращается ошибка, если не используется алгоритм шифрования, прошедший проверку подлинности. В последнем случае вызов обрабатывается как вызов шифрования с проверкой подлинности с данными нулевой длины, а тег проверки подлинности возвращается в параметре pPaddingInfo .

[in] cbOutput

Размер буфера pbOutput в байтах. Этот параметр игнорируется, если параметр pbOutput имеет значение NULL.

[out] pcbResult

Указатель на переменную ULONG , которая получает количество байтов, скопированных в буфер pbOutput . Если pbOutput имеет значение NULL, он получает размер в байтах, необходимый для зашифрованного текста.

[in] dwFlags

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

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

Значение	Значение
BCRYPT_BLOCK_PADDING	Позволяет алгоритму шифрования заполнять данные до следующего размера блока. Если этот флаг не указан, размер открытого текста, указанный в параметре cbInput , должен быть кратным размеру блока алгоритма. Размер блока можно получить, вызвав функцию BCryptGetProperty , чтобы получить свойство BCRYPT_BLOCK_LENGTH для ключа. Это обеспечит размер блока для алгоритма. Этот флаг не должен использоваться с режимами шифрования, прошедшими проверку подлинности (AES-CCM и AES-GCM).

Значение

BCRYPT_BLOCK_PADDING

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

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

Этот флаг не должен использоваться с режимами шифрования, прошедшими проверку подлинности (AES-CCM и AES-GCM).

Если ключ является асимметричным, это может быть одно из следующих значений.

Значение	Значение
BCRYPT_PAD_NONE	Не используйте никакое заполнение. Параметр pPaddingInfo не используется. Размер открытого текста, указанный в параметре cbInput , должен быть кратным размеру блока алгоритма.
BCRYPT_PAD_OAEP	Используйте схему оптимального заполнения асимметричного шифрования (OAEP). Параметр pPaddingInfo является указателем на структуру BCRYPT_OAEP_PADDING_INFO .
BCRYPT_PAD_PKCS1	Данные будут заполнены случайным числом для округления размера блока. Параметр pPaddingInfo не используется.

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

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

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

Код возврата	Описание
STATUS_SUCCESS	Функция выполнена успешно.
STATUS_BUFFER_TOO_SMALL	Размер, заданный параметром cbOutput , недостаточно велик для хранения зашифрованного текста.
STATUS_INVALID_BUFFER_SIZE	Параметр cbInput не кратен размеру блока алгоритма, а BCRYPT_BLOCK_PADDING или флаг BCRYPT_PAD_NONE не был указан в параметре dwFlags .
STATUS_INVALID_HANDLE	Дескриптор ключа в параметре hKey недопустим.
STATUS_INVALID_PARAMETER	Один или несколько параметров являются недопустимыми.
STATUS_NOT_SUPPORTED	Алгоритм не поддерживает шифрование.

Параметры pbInput и pbOutput могут быть равными. В этом случае эта функция будет выполнять шифрование на месте. Возможно, размер зашифрованных данных будет больше, чем размер незашифрованных данных, поэтому буфер должен быть достаточно большим для хранения зашифрованных данных. Если pbInput и pbOutput не равны, два буфера могут не перекрываться.

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

Чтобы вызвать эту функцию в режиме ядра, используйте 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

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

BCryptDecrypt

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