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

Статья
08/27/2023

Функция CryptMsgControl выполняет операцию управления после того, как сообщение было декодировано окончательным вызовом функции CryptMsgUpdate . Операции управления, предоставляемые этой функцией, используются для расшифровки, проверки подписи и хэша, а также для добавления и удаления сертификатов, списков отзыва сертификатов (CRL), подписывателей и атрибутов без проверки подлинности.

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

Синтаксис

BOOL CryptMsgControl(
  [in] HCRYPTMSG  hCryptMsg,
  [in] DWORD      dwFlags,
  [in] DWORD      dwCtrlType,
  [in] void const *pvCtrlPara
);

Параметры

[in] hCryptMsg

Дескриптор криптографического сообщения, к которому применяется элемент управления.

[in] dwFlags

Следующее значение определяется, если параметр dwCtrlType имеет одно из следующих значений:

CMSG_CTRL_DECRYPT
CMSG_CTRL_KEY_TRANS_DECRYPT
CMSG_CTRL_KEY_AGREE_DECRYPT
CMSG_CTRL_MAIL_LIST_DECRYPT

Значение	Значение
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Дескриптор поставщика шифрования освобождается при последнем вызове функции CryptMsgClose . Этот дескриптор не освобождается при сбое функции CryptMsgControl .

Если параметр dwCtrlType не указывает операцию расшифровки, присвойте этому значению нулевое значение.

[in] dwCtrlType

Тип выполняемой операции. В следующей таблице показаны текущие типы элементов управления сообщениями и тип структуры, который должен передаваться параметру pvCtrlPara .

Значение	Значение
CMSG_CTRL_ADD_ATTR_CERT 14 (0xE)	Большой двоичный объект, содержащий закодированные байты сертификата атрибута.
CMSG_CTRL_ADD_CERT 10 (0xA)	Структура CRYPT_INTEGER_BLOB , содержащая закодированные байты сертификата, добавляемого в сообщение.
CMSG_CTRL_ADD_CMS_SIGNER_INFO 20 (0x14)	Структура CMSG_CMS_SIGNER_INFO , содержащая сведения о подписывшем. Эта операция отличается от CMSG_CTRL_ADD_SIGNER тем, что сведения подписывателя содержат сигнатуру.
CMSG_CTRL_ADD_CRL 12 (0xC)	Большой двоичный объект, содержащий закодированные байты списка отзыва сертификатов, добавляемого в сообщение.
CMSG_CTRL_ADD_SIGNER 6 (0x6)	Структура CMSG_SIGNER_ENCODE_INFO , содержащая сведения о подписывшем, добавляемом в сообщение.
CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR 8 (0x8)	Структура CMSG_CTRL_ADD_SIGNER_UNAUTH_ATTR_PARA , содержащая индекс подписывающего и большой двоичный объект, содержащий сведения об атрибутах без проверки подлинности, добавляемые в сообщение.
CMSG_CTRL_DECRYPT 2 (0x2)	Структура CMSG_CTRL_DECRYPT_PARA , используемая для расшифровки сообщения для указанного получателя транспорта ключа. Это значение применимо к получателям RSA. Эта операция указывает, что функция CryptMsgControl выполняет поиск по индексу получателя для получения сведений о получателе передачи ключа. В случае сбоя функции GetLastError вернет CRYPT_E_INVALID_INDEX , если получатель транспорта ключа не найден.
CMSG_CTRL_DEL_ATTR_CERT 15 (0xF)	Индекс удаляемого сертификата атрибута.
CMSG_CTRL_DEL_CERT 11 (0xB)	Индекс сертификата, удаляемого из сообщения.
CMSG_CTRL_DEL_CRL 13 (0xD)	Индекс списка отзыва сертификатов, удаляемого из сообщения.
CMSG_CTRL_DEL_SIGNER 7 (0x7)	Индекс удаляемого подписывателя.
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR 9 (0x9)	Структура CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR_PARA , содержащая индекс, указывающий подписывающего, и индекс, указывающий удаляемые атрибуты подписывателя без проверки подлинности.
CMSG_CTRL_ENABLE_STRONG_SIGNATURE 21 (0x15)	Структура CERT_STRONG_SIGN_PARA , используемая для проверки строгой сигнатуры. Чтобы проверка для строгой сигнатуры, укажите этот тип элемента управления перед вызовом CryptMsgGetAndVerifySigner или перед вызовом CryptMsgControl со следующими заданными типами элементов управления: CMSG_CTRL_VERIFY_SIGNATURE CMSG_CTRL_VERIFY_SIGNATURE_EX После успешной проверки подписи эта функция проверяет наличие надежной сигнатуры. Если сигнатура не является строгой, операция завершится ошибкой, а для параметра GetLastError будет заданозначение NTE_BAD_ALGID.
CMSG_CTRL_KEY_AGREE_DECRYPT 17 (0x11)	Структура CMSG_CTRL_KEY_AGREE_DECRYPT_PARA , используемая для расшифровки сообщения для указанного ключа сеанса соглашения ключа. Соглашение о ключе используется с Diffie-Hellman шифрования и расшифровки.
CMSG_CTRL_KEY_TRANS_DECRYPT 16 (0x10)	Структура CMSG_CTRL_KEY_TRANS_DECRYPT_PARA , используемая для расшифровки сообщения для указанного получателя транспорта ключа. Передача ключей используется с шифрованием и расшифровкой RSA.
CMSG_CTRL_MAIL_LIST_DECRYPT 18 (0x12)	Структура CMSG_CTRL_MAIL_LIST_DECRYPT_PARA , используемая для расшифровки сообщения для указанного получателя с помощью ранее распределенного ключа шифрования ключей (KEK).
CMSG_CTRL_VERIFY_HASH 5 (0x5)	Это значение не используется.
CMSG_CTRL_VERIFY_SIGNATURE 1 (0x1)	Структура CERT_INFO , которая идентифицирует подписывателя сообщения, подпись которого требуется проверить.
CMSG_CTRL_VERIFY_SIGNATURE_EX 19 (0x13)	Структура CMSG_CTRL_VERIFY_SIGNATURE_EX_PARA , указывающая индекс подписывающего и открытый ключ для проверки подписи сообщения. Открытый ключ подписывающего может быть CERT_PUBLIC_KEY_INFO структурой, контекстом сертификата или контекстом цепочки сертификатов.

[in] pvCtrlPara

Указатель на структуру, определяемую значением dwCtrlType.

Значение dwCtrlType	Значение
CMSG_CTRL_DECRYPT, CMSG_CTRL_KEY_TRANS_DECRYPT, CMSG_CTRL_KEY_AGREE_DECRYPT или CMSG_CTRL_MAIL_LIST_DECRYPT и расшифровывается сообщение в потоке	Декодирование будет выполняться так, как будто расшифровывается потоковая передача содержимого. Если какое-либо зашифрованное потоковое содержимое накопилось до этого вызова, то часть или весь открытый текст , полученный в результате расшифровки зашифрованного текста, передается приложению через функцию обратного вызова, указанную в вызове функции CryptMsgOpenToDecode . Примечание При потоковой передаче конвертированного сообщения функция CryptMsgControl не вызывается до успешного опроса доступности CMSG_ENVELOPE_ALGORITHM_PARAM. Если опрос не выполнен, возникает ошибка. Описание этого опроса см. в разделе Функция CryptMsgOpenToDecode .
CMSG_CTRL_VERIFY_HASH	Хэш, вычисленный на основе содержимого сообщения, сравнивается с хэшом, содержащимся в сообщении.
CMSG_CTRL_ADD_SIGNER	pvCtrlPara указывает на структуру CMSG_SIGNER_ENCODE_INFO , содержащую сведения о подписывшем, добавляемые в сообщение.
CMSG_CTRL_DEL_SIGNER	После удаления все остальные индексы подписывающей стороны, используемые для этого сообщения, становятся недействительными, и их необходимо повторно запрашивать путем вызова функции CryptMsgGetParam .
CMSG_CTRL_DEL_SIGNER_UNAUTH_ATTR	После удаления все остальные индексы атрибутов без проверки подлинности, используемые для этого подписывающей стороны, становятся недействительными, и их необходимо повторно запрашивать, вызвав функцию CryptMsgGetParam .
CMSG_CTRL_DEL_CERT	После удаления все остальные индексы сертификатов, используемые для этого сообщения, становятся недействительными, и их необходимо повторно запрашивать путем вызова функции CryptMsgGetParam .
CMSG_CTRL_DEL_CRL	После удаления все остальные индексы списка отзыва сертификатов, используемые для этого сообщения, становятся недействительными, и их потребуется повторно получить, вызвав функцию CryptMsgGetParam .

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

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

Если функция завершается сбоем, возвращаемое значение равно нулю, а функция GetLastError возвращает ошибку кодирования и декодирования абстрактной синтаксической нотации 1 (ASN.1). Сведения об этих ошибках см. в разделе Кодирование и декодирование возвращаемых значений ASN.1.

При декодировании потокового конвертированного сообщения возникают ошибки в функции обратного вызова, определяемой приложением, заданной параметром pStreamInfo
Функция CryptMsgOpenToDecode может быть распространена на функцию CryptMsgControl. В этом случае функция SetLastError не вызывается функцией CryptMsgControl после возврата функции обратного вызова. При этом все ошибки, возникающие под контролем приложения, сохраняются. Функция обратного вызова (или один из вызываемых API) отвечает за вызов функции SetLastError , если во время обработки потоковых данных приложением возникает ошибка.

В следующих функциях могут возникать распространенные ошибки:

Чаще всего возвращаются следующие коды ошибок.

Код возврата	Описание
CRYPT_E_ALREADY_DECRYPTED	Содержимое сообщения уже расшифровано. Эта ошибка может быть возвращена, если параметру dwCtrlType присвоено значение CMSG_CTRL_DECRYPT.
CRYPT_E_AUTH_ATTR_MISSING	Сообщение не содержит ожидаемого атрибута, прошедшего проверку подлинности. Эта ошибка может быть возвращена, если параметру dwCtrlType присвоено значение CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_BAD_ENCODE	При кодировании или декодировании произошла ошибка. Эта ошибка может быть возвращена, если параметру dwCtrlType присвоено значение CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_CONTROL_TYPE	Недопустимый тип элемента управления.
CRYPT_E_HASH_VALUE	Неверное значение хэша.
CRYPT_E_INVALID_INDEX	Недопустимое значение индекса.
CRYPT_E_INVALID_MSG_TYPE	Недопустимый тип сообщения.
CRYPT_E_OID_FORMAT	Идентификатор объекта имеет неправильный формат. Эта ошибка может быть возвращена, если параметру dwCtrlType присвоено значение CMSG_CTRL_ADD_SIGNER.
CRYPT_E_RECIPIENT_NOT_FOUND	Сообщение с запечатанными данными не содержит указанного получателя. Эта ошибка может быть возвращена, если параметру dwCtrlType присвоено значение CMSG_CTRL_DECRYPT.
CRYPT_E_SIGNER_NOT_FOUND	Указанный подписыватель для сообщения не найден. Эта ошибка может быть возвращена, если параметру dwCtrlType присвоено значение CMSG_CTRL_VERIFY_SIGNATURE.
CRYPT_E_UNKNOWN_ALGO	Алгоритм шифрования неизвестен.
CRYPT_E_UNEXPECTED_ENCODING	Сообщение не закодировано должным образом. Эта ошибка может быть возвращена, если параметру dwCtrlType присвоено значение CMSG_CTRL_VERIFY_SIGNATURE.
E_INVALIDARG	Один или несколько аргументов недопустимы. Эта ошибка может быть возвращена, если параметру dwCtrlType присвоено значение CMSG_CTRL_DECRYPT.
E_OUTOFMEMORY	Недостаточно памяти для завершения операции.

Требования

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

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

Функции сообщений низкого уровня

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

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