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

Статья
08/27/2023

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

Синтаксис

HCRYPTMSG CryptMsgOpenToEncode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           void const        *pvMsgEncodeInfo,
  [in, optional] LPSTR             pszInnerContentObjID,
  [in]           PCMSG_STREAM_INFO pStreamInfo
);

Параметры

[in] dwMsgEncodingType

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

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING

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

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFlags

В следующей таблице приведены определенные в настоящее время dwFlags .

Значение	Значение
CMSG_BARE_CONTENT_FLAG	Потоковые выходные данные не будут иметь внешнюю оболочку ContentInfo (как определено в PKCS 7). Это делает его пригодным для потоковой передачи во включающее сообщение.
CMSG_DETACHED_FLAG	Для последующих вызовов CryptMsgUpdate предоставляются отсоединяемые данные.
CMSG_AUTHENTICATED_ATTRIBUTES_FLAG	Атрибуты, прошедшие проверку подлинности, принудительно включаются в SignerInfo (как определено в PKCS 7) в тех случаях, когда в противном случае они не были бы обязательными.
CMSG_CONTENTS_OCTETS_FLAG	Используется при вычислении размера сообщения, которое было закодировано с помощью Distinguished Encoding Rules (DER) и вложено в конвертированное сообщение. Это особенно полезно при выполнении потоковой передачи.
CMSG_CMS_ENCAPSULATED_CONTENT_FLAG	Если этот параметр задан, внутреннее содержимое , отличное от типа данных, инкапсулируется в СТРОКУ OCTET. Применимо как к подписанным, так и к конвертным сообщениям.
CMSG_CRYPT_RELEASE_CONTEXT_FLAG	Если этот параметр задан, hCryptProv , передаваемый в эту функцию, освобождается в окончательном элементе CryptMsgUpdate. Дескриптор не освобождается при сбое функции. Примечание Файлы hCryptProvполучателей конверта не освобождаются.

[in] dwMsgType

Указывает тип сообщения. Это должно быть одно из следующих значений.

Значение	Значение
CMSG_DATA	Это значение не используется.
CMSG_SIGNED	Параметр pvMsgEncodeInfo — это адрес структуры CMSG_SIGNED_ENCODE_INFO , содержащей сведения о кодировке.
CMSG_ENVELOPED	Параметр pvMsgEncodeInfo — это адрес структуры CMSG_ENVELOPED_ENCODE_INFO , содержащей сведения о кодировке.
CMSG_SIGNED_AND_ENVELOPED	Это значение в настоящее время не реализовано.
CMSG_HASHED	Параметр pvMsgEncodeInfo — это адрес структуры CMSG_HASHED_ENCODE_INFO , содержащей сведения о кодировке.

[in] pvMsgEncodeInfo

Адрес структуры, содержащей сведения о кодировке. Тип данных зависит от значения параметра dwMsgType . Дополнительные сведения см. в разделе dwMsgType.

[in, optional] pszInnerContentObjID

Если вызывается CryptMsgCalculateEncodedLength и данные для CryptMsgUpdate уже закодированы, соответствующий идентификатор объекта (OID) передается в pszInnerContentObjID. Если pszInnerContentObjID имеет значение NULL, предполагается, что внутренний тип контента не был закодирован ранее и поэтому закодирован как строка октета и получает тип CMSG_DATA.

Примечание При использовании потоковой передачи pszInnerContentObjID должен иметь значение NULL или szOID_RSA_data.

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

szOID_RSA_data
szOID_RSA_signedData
szOID_RSA_envelopedData
szOID_RSA_signEnvData
szOID_RSA_digestedData
szOID_RSA_encryptedData
SPC_INDIRECT_DATA_OBJID

[in] pStreamInfo

При использовании потоковой передачи этот параметр является адресом структуры CMSG_STREAM_INFO . Функция обратного вызова, указанная членом pfnStreamOutput структуры CMSG_STREAM_INFO , вызывается при выполнении CryptMsgUpdate . Обратный вызов передает закодированные байты, полученные в результате кодирования. Дополнительные сведения об использовании обратного вызова см. в разделе CMSG_STREAM_INFO.

Примечание При использовании потоковой передачи приложение не должно освобождать дескриптор данных, передаваемый в параметре pvMsgEncodeInfo , например дескриптор поставщика в элементе hCryptProvструктуры CMSG_SIGNER_ENCODE_INFO , до тех пор, пока дескриптор сообщения, возвращенный этой функцией, не будет закрыт с помощью функции CryptMsgClose .

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

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

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

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

Если функция выполняется успешно, она возвращает дескриптор открытому сообщению. Этот дескриптор необходимо закрыть, если он больше не нужен, передав его в функцию CryptMsgClose .

Если эта функция завершается сбоем, возвращается значение NULL .

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

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

Код возврата	Описание
CRYPT_E_INVALID_MSG_TYPE	Недопустимый тип сообщения.
CRYPT_E_OID_FORMAT	OID имеет неправильный формат.
CRYPT_E_UNKNOWN_ALGO	Алгоритм шифрования неизвестен.
E_INVALIDARG	Один или несколько аргументов являются недопустимыми.
E_OUTOFMEMORY	Недостаточно памяти.

Кроме того, если параметр dwMsgType имеет CMSG_SIGNED, ошибки могут распространяться из CryptCreateHash.

Если параметр dwMsgType имеет CMSG_ENVELOPED, ошибки могут распространяться из CryptGenKey, CryptImportKey и CryptExportKey.

Если параметр dwMsgType имеет CMSG_HASHED, ошибки могут распространяться из CryptCreateHash.

Для функций, выполняющих шифрование, зашифрованные симметричные ключи переходят из формата с байтового байта в формат big-endian после внутреннего вызова CryptExportKey . Для функций, выполняющих расшифровку, зашифрованные симметричные ключи перед вызовом CryptImportKey переходят из формата big-endian в формат с маленьким байтом.

CRYPT_NO_SALT указывается при создании и импорте симметричного ключа с помощью CryptGenKey и CryptImportKey.

Сообщения, зашифрованные с помощью алгоритма шифрования RC2, используют KP_EFFECTIVE_KEYLEN с CryptGetKeyParam , чтобы определить эффективную длину ключа RC2, импортируемого или экспортируемого ключа.

Для сообщений, зашифрованных с помощью алгоритма шифрования RC2, операции кодирования и декодирования были обновлены для обработки параметров RC2 ASN для элемента ContentEncryptionAlgorithm структуры CMSG_ENVELOPED_ENCODE_INFO .

Для сообщений, зашифрованных с помощью алгоритмов шифрования RC4, DES и 3DES, операции кодирования и декодирования теперь обрабатывают строковый параметр октета ASN IV для элемента ContentEncryptionAlgorithm структуры CMSG_ENVELOPED_ENCODE_INFO .

Примеры

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

Требования

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