CryptMsgOpenToDecode 函式 (wincrypt.h)

發行項
03/03/2024

CryptMsgOpenToDecode 函式會開啟密碼編譯訊息以進行譯碼，並傳回已開啟之訊息的句柄。訊息會保持開啟狀態，直到呼叫 CryptMsgClose 函式為止。

對 CryptoAPI 處理會影響信封郵件處理的重要變更，以支援安全/多用途因特網郵件延伸模組 (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 結構。結構包含使用 pwszContainerName、pwszProvName、dwProvType 和 dwFlagsCRYPT_KEY_PROV_INFO 成員的 cryptAcquireContext 來取得收件者私鑰所需的資訊。取得的 hCryptProv 和 CRYPT_KEY_PROV_INFO 結構的 dwKeySpec 成員會傳遞至 CryptMsgControl 結構做為 CMSG_CTRL_DECRYPT_PARA 結構的成員，以允許內部內容的解密開始。串流程式代碼接著會在數據輸入時執行解密。產生的純文本區塊會傳遞至CMSG_STREAM_INFO 結構的 pfnStreamOutput 成員所指定的回呼函式，以處理解密訊息的輸出。

注意封包訊息的數據流譯碼會將記憶體中的加密文本排入佇列，直到呼叫 CryptMsgControl 以啟動解密為止。應用程式必須及時起始解密，讓數據可以儲存到磁碟或路由傳送到其他位置，累積的 加密文字 變得太大，而且系統記憶體不足。

如果是封入信封郵件中的帶正負號訊息，封包郵件串流譯碼的純文本輸出可以饋送至另一個串流譯碼來處理已簽署的訊息。

傳回值

如果函式成功，函式會傳回已開啟訊息的句柄。

如果函式失敗，它會傳回 NULL。如需擴充錯誤資訊，請呼叫 GetLastError。

下表列出 GetLastError 函式最常傳回的錯誤碼。

值	Description
E_INVALIDARG	一或多個自變數無效。
E_OUTOFMEMORY	發生記憶體配置失敗。

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	wincrypt.h
程式庫	Crypt32.lib
Dll	Crypt32.dll

另請參閱

共用方式為

CryptMsgOpenToDecode 函式 (wincrypt.h)

語法

參數

傳回值

規格需求

另請參閱

意見反應

其他資源