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

Статья
03/14/2023

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

Синтаксис

NTSTATUS BCryptDecrypt(
  [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 не используется.

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

[in] cbIV

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

[out, optional] pbOutput

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

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

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

[in] cbOutput

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

[out] pcbResult

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

[in] dwFlags

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

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

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

Значение

BCRYPT_BLOCK_PADDING

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

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

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

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

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

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

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

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

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

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

BCryptEncrypt