CryptMsgOpenToDecode 函数 (wincrypt.h)

项目
08/27/2023

CryptMsgOpenToDecode 函数打开加密消息进行解码，并返回打开的消息的句柄。在调用 CryptMsgClose 函数之前，消息将保持打开状态。

对 CryptoAPI 进行了影响信封邮件处理的重要更改，以支持安全/多用途 Internet 邮件扩展 (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

指定使用的编码类型。始终可以接受将证书和消息编码类型与按位 OR 操作组合在一起，如以下示例所示：

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 Explorer 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 后，必须检查通过调用 CryptMsgGetParam 函数来确定CMSG_ENVELOPE_ALGORITHM_PARAM属性是否可用。 CryptMsgGetParam 将失败， GetLastError 将返回CRYPT_E_STREAM_MSG_NOT_READY，直到 CryptMsgUpdate 处理足够的消息以使CMSG_ENVELOPE_ALGORITHM_PARAM属性可用。当 CMSG_ENVELOPE_ALGORITHM_PARAM 属性可用时，可以循环访问收件人，通过使用 CryptMsgGetParam 函数检索CMSG_RECIPIENT_INFO_PARAM属性，为每个收件人检索CERT_INFO结构。若要防止来自具有人为较大标头块的信封消息的拒绝服务攻击，必须跟踪在此过程中传递给 CryptMsgUpdate 函数的内存量。如果在 CMSG_ENVELOPE_ALGORITHM_PARAM 属性可用之前数据量超过应用程序定义的限制，则必须停止处理消息并调用 CryptMsgClose 函数，使操作系统释放已为消息分配的任何内存。建议的限制是允许的消息的最大大小。例如，如果最大消息大小为 10 MB，则此测试的限制应为 10 MB。

CERT_INFO结构用于使用 CertGetSubjectCertificateFromStore 函数在以前打开的证书存储中查找匹配的证书。找到正确的证书后，将调用具有 CERT_KEY_PROV_INFO_PROP_ID 参数的 CertGetCertificateContextProperty 函数来检索 CRYPT_KEY_PROV_INFO 结构。结构包含通过调用 CryptAcquireContext、使用CRYPT_KEY_PROV_INFO结构的 pwszContainerName、pwszProvName、dwProvType 和 dwFlags 成员获取收件人私钥所需的信息。获取的 hCryptProv 和 CRYPT_KEY_PROV_INFO 结构的 dwKeySpec 成员作为 CMSG_CTRL_DECRYPT_PARA 结构的成员传递给 CryptMsgControl 结构，以允许开始解密内部内容。然后，当输入数据时，流式处理代码将执行解密。生成的纯文本块将传递给由 CMSG_STREAM_INFO 结构的 pfnStreamOutput 成员指定的回调函数，以处理解密消息的输出。

注意对信封消息进行流式解码会将加密文本排在内存中，直到调用 CryptMsgControl 开始解密。应用程序必须及时启动解密，以便数据可以保存到磁盘或路由到其他位置，然后累积 的密码文本 变得太大，系统内存不足。

如果已签名消息包含在信封邮件中，则信封消息的流式解码的纯文本输出可以馈送到另一个流式解码中，以处理已签名的消息。

返回值

如果函数成功，该函数将返回已打开消息的句柄。

如果函数失败，它将返回 NULL。有关扩展的错误信息，请调用 GetLastError。

下表列出了 GetLastError 函数最常返回的错误代码。

值	说明
E_INVALIDARG	一个或多个参数无效。
E_OUTOFMEMORY	发生内存分配失败。

要求

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

另请参阅

通过

CryptMsgOpenToDecode 函数 (wincrypt.h)

语法

参数

返回值

要求

另请参阅

反馈

其他资源