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

Статья
03/15/2023

Функция CryptMsgOpenToDecode открывает криптографическое сообщение для декодирования и возвращает дескриптор открытого сообщения. Сообщение остается открытым до вызова функции CryptMsgClose .

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

Синтаксис

HCRYPTMSG CryptMsgOpenToDecode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           HCRYPTPROV_LEGACY hCryptProv,
  [in]           PCERT_INFO        pRecipientInfo,
  [in, optional] PCMSG_STREAM_INFO pStreamInfo
);

Параметры

[in] dwMsgEncodingType

Указывает используемый тип кодирования. Всегда допустимо указывать типы кодирования сертификатов и сообщений, объединяя их с побитовой операцией ИЛИ , как показано в следующем примере:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

В настоящее время определены следующие типы кодирования:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFlags

Этот параметр может быть одним из следующих флагов.

Значение	Значение
CMSG_DETACHED_FLAG	Указывает, что декодирование сообщения отсоединяется. Если этот флаг не установлен, сообщение не отсоединяется.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Если этот параметр задан, hCryptProv , переданный в эту функцию, освобождается в окончательном элементе CryptMsgUpdate. Дескриптор не освобождается при сбое функции.

[in] dwMsgType

Указывает тип декодированного сообщения. В большинстве случаев тип сообщения определяется из заголовка сообщения, а для этого параметра передается ноль. В некоторых случаях, в частности в Internet Обозреватель 3.0, сообщения не имеют заголовков, и в этом вызове функции необходимо указать тип декодированного сообщения. Если заголовок отсутствует и для этого параметра передается ноль, функция завершается ошибкой.

Этот параметр может быть одним из следующих предопределенных типов сообщений.

Значение	Значение
CMSG_DATA	Сообщение является закодированными данными.
CMSG_ENVELOPED	Сообщение представляет собой конвертированное сообщение.
CMSG_HASHED	Сообщение является хэш-сообщением.
CMSG_SIGNED	Сообщение является подписанным сообщением.
CMSG_SIGNED_AND_ENVELOPED	Сообщение представляет собой подписанное и конвертированное сообщение.

[in] hCryptProv

Этот параметр не используется и должен иметь значение NULL.

Windows Server 2003 и Windows XP: Указывает дескриптор для поставщика служб шифрования, который будет использоваться для хэширования сообщения. Для подписанных сообщений для проверки подписи используется hCryptProv . Тип данных этого параметра — HCRYPTPROV.

Если нет веской причины для передачи определенного поставщика шифрования в hCryptProv, задайте для этого параметра значение NULL. Передача значения NULL приводит к получению поставщика RSA или DSS по умолчанию перед выполнением операций хэша, проверки подписи или шифрования получателей.

[in] pRecipientInfo

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

[in, optional] pStreamInfo

Если потоковая передача не используется, этот параметр должен иметь значение NULL.

Примечание Потоковая передача не используется с CMSG_HASHED сообщениями. При работе с хэшированные данные для этого параметра необходимо задать значение NULL.

При использовании потоковой передачи параметр pStreamInfo является указателем на структуру CMSG_STREAM_INFO , которая содержит указатель на обратный вызов, вызываемый при выполнении CryptMsgUpdate или при выполнении CryptMsgControl при декодировании потокового конвертированного сообщения.

Для подписанного сообщения обратный вызов передается блок декодированных байтов из внутреннего содержимого сообщения.

Для конвертированного сообщения после каждого вызова CryptMsgUpdate необходимо проверка, чтобы определить, доступно ли свойство CMSG_ENVELOPE_ALGORITHM_PARAM, путем вызова функции CryptMsgGetParam. CryptMsgGetParam завершится ошибкой , и GetLastError вернет CRYPT_E_STREAM_MSG_NOT_READY, пока CryptMsgUpdate не обработает достаточно сообщения, чтобы сделать свойство CMSG_ENVELOPE_ALGORITHM_PARAM доступным. Когда свойство CMSG_ENVELOPE_ALGORITHM_PARAM доступно, можно выполнить итерацию по получателям, получив структуру CERT_INFO для каждого получателя с помощью функции CryptMsgGetParam для получения свойства CMSG_RECIPIENT_INFO_PARAM. Чтобы предотвратить атаку типа "отказ в обслуживании" из конвертированного сообщения с искусственно большим блоком заголовков, необходимо отслеживать объем памяти, переданный функции CryptMsgUpdate во время этого процесса. Если объем данных превышает ограничение, определенное приложением, прежде чем свойство CMSG_ENVELOPE_ALGORITHM_PARAM будет доступно, необходимо остановить обработку сообщения и вызвать функцию CryptMsgClose , чтобы операционная система освободила память, выделенную для сообщения. Рекомендуемое ограничение — это максимально допустимый размер сообщения. Например, если максимальный размер сообщения составляет 10 МБ, ограничение для этого теста должно составлять 10 МБ.

Структура CERT_INFO используется для поиска соответствующего сертификата в ранее открытом хранилище сертификатов с помощью функции CertGetSubjectCertificateFromStore . При обнаружении правильного сертификата вызывается функция CertGetCertificateContextProperty с параметром CERT_KEY_PROV_INFO_PROP_ID для получения структуры CRYPT_KEY_PROV_INFO . Структура содержит сведения, необходимые для получения закрытого ключа получателя путем вызова CryptAcquireContext с помощью элементов pwszContainerName, pwszProvName, dwProvType и dwFlags структуры CRYPT_KEY_PROV_INFO . Полученный hCryptProv и член dwKeySpecструктуры CRYPT_KEY_PROV_INFO передаются в структуру CryptMsgControl в качестве члена структуры CMSG_CTRL_DECRYPT_PARA , чтобы разрешить начало расшифровки внутреннего содержимого. Затем код потоковой передачи выполнит расшифровку по мере ввода данных. Результирующий блок открытого текста передается в функцию обратного вызова, заданную членом pfnStreamOutput структуры CMSG_STREAM_INFO для обработки выходных данных расшифрованного сообщения.

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

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

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

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

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

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

Значение	Описание
E_INVALIDARG	Один или несколько аргументов являются недопустимыми.
E_OUTOFMEMORY	Произошел сбой выделения памяти.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	wincrypt.h
Библиотека	Crypt32.lib
DLL	Crypt32.dll

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

Низкоуровневые функции сообщений

Упрощенные функции сообщений