CryptMsgOpenToDecode 函式 (wincrypt.h)

  • 發行項

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

另請參閱

CryptMsgClose

CryptMsgGetParam

CryptMsgOpenToEncode

CryptMsgUpdate

低階訊息函式

簡化的訊息函式