CryptMsgOpenToEncode 函数 (wincrypt.h)

项目
03/13/2024

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

指定使用的编码类型。始终可以通过将证书和消息编码类型与按位 OR 操作结合使用来指定它们，如以下示例所示：

X509_ASN_ENCODING |PKCS_7_ASN_ENCODING

当前定义的编码类型为：

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFlags

下表显示了当前定义的 dwFlags 。

值	含义
CMSG_BARE_CONTENT_FLAG	流式输出没有 PKCS #7) 定义的外部 ContentInfo 包装器 (。这使得它适合流式传输到封闭消息中。
CMSG_DETACHED_FLAG	为对 CryptMsgUpdate 的后续调用提供分离数据。
CMSG_AUTHENTICATED_ATTRIBUTES_FLAG	如 PKCS #7) 定义的那样，强制将经过身份验证的属性包含在 SignerInfo (中，否则不需要它们。
CMSG_CONTENTS_OCTETS_FLAG	在计算已使用可辨别编码规则 ( DER) 编码并嵌套在信封邮件内的消息的大小时使用。这在执行流式处理时特别有用。
CMSG_CMS_ENCAPSULATED_CONTENT_FLAG	设置后，非数据类型内部内容封装在 OCTET STRING 中。适用于签名邮件和带信封的邮件。
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 的数据进行消息编码，则会在 pszInnerContentObjID 中传递相应的对象标识符 (OID) 。如果 pszInnerContentObjID 为 NULL，则假定内部内容类型以前未编码，因此被编码为八进制字符串，并给定类型CMSG_DATA。

注意使用流式处理时， pszInnerContentObjID 必须为 NULL 或 szOID_RSA_data。

通常使用以下算法 OID。用户可以通过确保消息的发送方和接收方同意与 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 结构的地址。执行 CryptMsgUpdate 时，将调用 CMSG_STREAM_INFO 结构的 pfnStreamOutput 成员指定的回调函数。回调将传递编码产生的编码字节。有关如何使用回调的详细信息，请参阅 CMSG_STREAM_INFO。

注意在使用流式处理时，应用程序不得释放在 pvMsgEncodeInfo 参数中传递的任何数据句柄，例如CMSG_SIGNER_ENCODE_INFO结构的 hCryptProv 成员中的提供程序句柄，直到使用 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	内存不足。

此外，如果 CMSG_SIGNED dwMsgType ，则可以从 CryptCreateHash 传播错误。

如果 dwMsgType 是CMSG_ENVELOPED，则可以从 CryptGenKey、 CryptImportKey 和 CryptExportKey 传播错误。

如果 dwMsgType 是CMSG_HASHED，则可以从 CryptCreateHash 传播错误。

注解

对于执行加密的函数，在内部调用 CryptExportKey 后，加密的对称密钥将从小端格式反转为 big-endian 格式。对于执行解密的函数，在调用 CryptImportKey 之前，加密的对称密钥将从 big-endian 格式反转为 little-endian 格式。

CRYPT_NO_SALT是在使用 CryptGenKey 和 CryptImportKey 生成和导入对称密钥时指定的。

使用 RC2 加密算法加密的消息使用 KP_EFFECTIVE_KEYLEN 和 CryptGetKeyParam 来确定 RC2 密钥导入或导出密钥的有效密钥长度。

对于使用 RC2 加密算法加密的消息，已更新编码和解码操作，以处理 CMSG_ENVELOPED_ENCODE_INFO 结构的 ContentEncryptionAlgorithm 成员的 ASN RC2 参数。

对于使用 RC4、DES 和 3DES 加密算法加密的消息，编码和解码操作现在处理 CMSG_ENVELOPED_ENCODE_INFO 结构的 ContentEncryptionAlgorithm 成员的 ASN IV 八进制字符串参数。

示例

有关使用此函数的示例，请参阅示例 C 程序：对消息进行签名、编码、解码和验证、对信封邮件进行编码的备用代码、示例 C 程序：编码信封、签名的消息和示例 C 程序：编码和解码哈希消息。

要求

要求	值
最低受支持的客户端	Windows XP [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2003 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	wincrypt.h
Library	Crypt32.lib
DLL	Crypt32.dll