Функция CryptDecrypt (wincrypt.h)

Статья
07/16/2024

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

Функция CryptDecrypt расшифровывает данные, ранее зашифрованные с помощью функции CryptEncrypt.

Важные изменения в поддержке Secure/Multipurpose Internet Mail Extensions (S/MIME) для взаимодействия с электронной почтой были сделаны в CryptoAPI, которые влияют на обработку конвертированных сообщений. Дополнительные сведения см. в разделе "Примечания" CryptMsgOpenToEncode.

Синтаксис

BOOL CryptDecrypt(
  [in]      HCRYPTKEY  hKey,
  [in]      HCRYPTHASH hHash,
  [in]      BOOL       Final,
  [in]      DWORD      dwFlags,
  [in, out] BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen
);

Параметры

[in] hKey

Дескриптор ключа, используемый для расшифровки. Приложение получает этот дескриптор с помощью функции CryptGenKey или CryptImportKey.

Этот ключ задает используемый алгоритм расшифровки.

[in] hHash

Дескриптор хэш-объекта . Если данные должны быть расшифрованы и хэшированы одновременно, дескриптор в хэш-объект передается в этом параметре. Хэш-значение обновляется с помощью расшифрованных открытого текста. Этот параметр полезен при одновременном расшифровке и проверке подписи.

Перед вызовом CryptDecryptприложение должно получить дескриптор хэш-объекта, вызвав функцию CryptCreateHash. После завершения расшифровки хэш-значение можно получить с помощью функции CryptGetHashParam, ее также можно подписать с помощью функции CryptSignHash или использовать для проверки цифровой подписи с помощью функции CryptVerifySignature.

Если хэш не выполняется, этот параметр должен быть равен нулю.

[in] Final

Логическое значение, указывающее, является ли это последним разделом в расшифровке серии. Это значение TRUE, если это последний или единственный блок. Если это не последний блок, это значение FALSE. Дополнительные сведения см. в разделе "Примечания".

[in] dwFlags

Определены следующие значения флагов.

Ценность	Значение
CRYPT_OAEP 0x00000040	Используйте оптимальную асимметричную заполнения шифрования (OAEP) (PKCS #1 версии 2). Этот флаг поддерживается только расширенным поставщиком шифрования Майкрософт с шифрованием ИЛИ расшифровкой RSA. Этот флаг нельзя объединить с флагом CRYPT_DECRYPT_RSA_NO_PADDING_CHECK.
CRYPT_DECRYPT_RSA_NO_PADDING_CHECK 0x00000020	Расшифровка BLOB без проверки заполнения. Этот флаг поддерживается только расширенным поставщиком шифрования Майкрософт с шифрованием ИЛИ расшифровкой RSA. Этот флаг нельзя объединить с флагом CRYPT_OAEP.

Ценность

Значение

CRYPT_OAEP
0x00000040

Используйте оптимальную асимметричную заполнения шифрования (OAEP) (PKCS #1 версии 2). Этот флаг поддерживается только расширенным поставщиком шифрования Майкрософт с шифрованием ИЛИ расшифровкой RSA. Этот флаг нельзя объединить с флагом CRYPT_DECRYPT_RSA_NO_PADDING_CHECK.

CRYPT_DECRYPT_RSA_NO_PADDING_CHECK
0x00000020

Расшифровка BLOB без проверки заполнения. Этот флаг поддерживается только расширенным поставщиком шифрования Майкрософт с шифрованием ИЛИ расшифровкой RSA. Этот флаг нельзя объединить с флагом CRYPT_OAEP.

[in, out] pbData

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

Число зашифрованных байтов в этом буфере указывается pdwDataLen.

[in, out] pdwDataLen

Указатель на значение DWORD, указывающее длину буфера pbData . Перед вызовом этой функции вызывающее приложение задает значение DWORD количество байтов, которые необходимо расшифровать. По возвращении значение DWORD содержит число байтов расшифрованного открытого текста.

Если используется блочного шифра , эта длина данных должна быть кратной, если это не окончательный раздел данных для расшифровки, а параметр Final — TRUE.

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

Если функция выполнена успешно, функция возвращает ненулевое значение (TRUE).

Если функция завершается ошибкой, она возвращает ноль (FALSE). Для получения расширенных сведений об ошибке вызовите GetLastError.

Коды ошибок, предуставленные NTE, создаются конкретным используемым поставщиком служб CSP. Ниже приведены некоторые возможные коды ошибок.

Ценность	Описание
ERROR_INVALID_HANDLE	Один из параметров задает недопустимый дескриптор.
ERROR_INVALID_PARAMETER	Один из параметров содержит недопустимое значение. Чаще всего это недопустимый указатель.
NTE_BAD_ALGID	Ключ сеанса hKey задает алгоритм, который не поддерживается этим поставщиком служб CSP.
NTE_BAD_DATA	Расшифрованные данные недопустимы. Например, если используется шифр блока и флаг окончательного имеет значение false FALSE, то значение, указанное в pdwDataLen, должно иметь несколько размеров блока. Эта ошибка также может быть возвращена, если заполнение не является допустимым.
NTE_BAD_FLAGS	Параметр dwFlags ненулево.
NTE_BAD_HASH	Параметр hHash содержит недопустимый дескриптор.
NTE_BAD_KEY	Параметр hKey не содержит допустимый дескриптор ключа.
NTE_BAD_LEN	Размер выходного буфера слишком мал для хранения созданного открытого текста.
NTE_BAD_UID	Контекст CSP, указанный при создании ключа, не найден.
NTE_DOUBLE_ENCRYPT	Приложение попыталось расшифровать одни и те же данные дважды.
NTE_FAIL	Функция завершилась сбоем каким-то неожиданным образом.

Замечания

Если требуется расшифровать большой объем данных, его можно сделать в разделах, вызвав CryptDecrypt. Параметр Final должен иметь значение TRUE только при последнем вызове CryptDecrypt, чтобы модуль расшифровки смог правильно завершить процесс расшифровки. Следующие дополнительные действия выполняются при окончательныхTRUE:

Если ключ является ключом блочного шифра, данные заполняются на несколько размеров блока шифра. Чтобы найти размер блока шифра, используйте CryptGetKeyParam, чтобы получить значение KP_BLOCKLEN ключа.
Если шифр работает в режиме цепочки , следующая операция CryptDecrypt сбрасывает регистр обратной связи шифра в значение KP_IV ключа.
Если шифр являетсяшифром потока , следующий вызов CryptDecrypt сбрасывает шифр на исходное состояния.

Невозможно задать регистр обратной связи шифра в значение KP_IV ключа, не задав параметру Final значение TRUE. Если это необходимо, как и в случае, если вы не хотите добавить дополнительный блок заполнения или изменить размер каждого блока, можно имитировать его, создав дубликат исходного ключа с помощью функции CryptDuplicateKey и передачи дубликата ключа в функцию CryptDecrypt. Это приводит к тому, что KP_IV исходного ключа помещаются в повторяющийся ключ. После создания или импорта исходного ключа не удается использовать исходный ключ для шифрования, так как регистр обратной связи ключа будет изменен. В следующем псевдокоде показано, как это можно сделать.

// Set the IV for the original key. Do not use the original key for 
// encryption or decryption after doing this because the key's 
// feedback register will get modified and you cannot change it.
CryptSetKeyParam(hOriginalKey, KP_IV, newIV)

while(block = NextBlock())
{
    // Create a duplicate of the original key. This causes the 
    // original key's IV to be copied into the duplicate key's 
    // feedback register.
    hDuplicateKey = CryptDuplicateKey(hOriginalKey)

    // Decrypt the block with the duplicate key.
    CryptDecrypt(hDuplicateKey, block)

    // Destroy the duplicate key. Its feedback register has been 
    // modified by the CryptEncrypt function, so it cannot be used
    // again. It will be re-duplicated in the next iteration of the 
    // loop.
    CryptDestroyKey(hDuplicateKey)
}

расширенного поставщика шифрования Майкрософт поддерживает прямое шифрование с помощью RSA открытых ключей и расшифровки с помощью закрытых ключей RSA . Шифрование использует PKCS #1 заполнение. При расшифровке этот заполнение проверяется. Длина расшифровки шифров данных должна быть той же длиной, что и модуль ключа RSA, используемого для расшифровки данных. Если зашифрованный текст имеет нули в наиболее значимых байтах, эти байты должны быть включены в буфер входных данных и в длину входного буфера. Шифр должен быть в формате маленький.

Примеры

Пример использования этой функции см. в разделе Пример программы C: расшифровка файла.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	wincrypt.h
библиотеки	Advapi32.lib
DLL	Advapi32.dll