cryptMsgControl 函数 (wincrypt.h)

  • 项目

CryptMsgControl 函数在最终调用 CryptMsgUpdate 函数解码消息后执行控制操作。 此函数提供的控制操作用于解密、签名和哈希验证，以及添加和删除证书、 证书吊销列表 (CRL) 、签名者和未经身份验证的属性。

对 CryptoAPI 进行了影响信封邮件处理的重要更改，以支持 安全/多用途 Internet 邮件扩展 (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)
 包含属性证书的编码字节的 BLOB 。
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)
 一个 BLOB，其中包含要添加到消息的 CRL 的编码字节。
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 结构，以及包含要添加到消息的未经身份验证的属性信息的 BLOB。
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)
 要从消息中删除的 CRL 的索引。
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 函数的调用中指定的回调函数，将密码文本解密产生的部分或全部纯文本传递回应用程序。
注意 流式传输信封消息时，在轮询CMSG_ENVELOPE_ALGORITHM_PARAM可用性成功之前，不会调用 CryptMsgControl 函数。 如果轮询不成功，则会导致错误。 有关该轮询的说明，请参阅 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
 删除后，用于此消息的任何其他 CRL 索引不再有效，需要通过调用 CryptMsgGetParam 函数重新获取。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零， GetLastError 函数返回 抽象语法表示法 1 (ASN.1) 编码/解码错误。 有关这些错误的信息，请参阅 ASN.1 编码/解码返回值。

当对流式传输的信封消息进行解码时，在 由 的 pStreamInfo 参数指定的应用程序定义的回调函数中遇到错误
CryptMsgOpenToDecode 函数可能会传播到 CryptMsgControl 函数。 如果发生这种情况，则回调函数返回后，CryptMsgControl 函数不会调用 SetLastError 函数。 这将保留应用程序控制下遇到的任何错误。 回调函数 (或调用的 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
标头 wincrypt.h
Library Crypt32.lib
DLL Crypt32.dll

另请参阅

低级别消息函数

简化的消息函数