CryptMsgControl 函式 (wincrypt.h)

  • 發行項

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)
包含屬性憑證編碼位元組的 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 函式會傳回 抽象語法表示法 One (ASN.1) 編碼/譯碼錯誤。 如需這些錯誤的相關信息，請參閱 ASN.1 編碼/譯碼傳回值。

當數據流化、信封訊息被譯碼時，在 由的 pStreamInfo 參數所指定的應用程式定義回呼函式中發生錯誤
CryptMsgOpenToDecode 函式可能會傳播至 CryptMsgControl 函式。 如果發生這種情況，在回呼函式傳回之後，CryptMsgControl 函式不會呼叫 SetLastError 函式。 這會保留應用程式控制下遇到的任何錯誤。 如果應用程式正在處理串流數據時發生錯誤，則回呼函式 (或其中一個 API 會呼叫) 呼叫 SetLastError 函式。

從下列函式可能會遇到傳播錯誤：

最常傳回下列錯誤碼。

傳回碼 Description
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
程式庫 Crypt32.lib
Dll Crypt32.dll

另請參閱

低階訊息函式

簡化的訊息函式