Функция BCryptEncrypt (bcrypt.h)
Функция 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 .
Если ключ является симметричным, это может быть ноль или следующее значение.
| Значение | Значение |
|---|---|
|
Позволяет алгоритму шифрования заполнять данные до следующего размера блока. Если этот флаг не указан, размер открытого текста, указанный в параметре cbInput , должен быть кратным размеру блока алгоритма.
Размер блока можно получить, вызвав функцию BCryptGetProperty , чтобы получить свойство BCRYPT_BLOCK_LENGTH для ключа. Это обеспечит размер блока для алгоритма. Этот флаг не должен использоваться с режимами шифрования, прошедшими проверку подлинности (AES-CCM и AES-GCM). |
Если ключ является асимметричным, это может быть одно из следующих значений.
| Значение | Значение |
|---|---|
|
Не используйте никакое заполнение. Параметр pPaddingInfo не используется. Размер открытого текста, указанный в параметре cbInput , должен быть кратным размеру блока алгоритма. |
|
Используйте схему оптимального заполнения асимметричного шифрования (OAEP). Параметр pPaddingInfo является указателем на структуру BCRYPT_OAEP_PADDING_INFO . |
|
Данные будут заполнены случайным числом для округления размера блока. Параметр pPaddingInfo не используется. |
Возвращаемое значение
Возвращает код состояния, указывающий на успешное или неудачное выполнение функции.
Возможные коды возврата включают, помимо прочего, следующие.
| Код возврата | Описание |
|---|---|
|
Функция выполнена успешно. |
|
Размер, заданный параметром cbOutput , недостаточно велик для хранения зашифрованного текста. |
|
Параметр cbInput не кратен размеру блока алгоритма, а BCRYPT_BLOCK_PADDING или флаг BCRYPT_PAD_NONE не был указан в параметре dwFlags . |
|
Дескриптор ключа в параметре hKey недопустим. |
|
Один или несколько параметров являются недопустимыми. |
|
Алгоритм не поддерживает шифрование. |
Комментарии
Параметры 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 |