CryptMsgOpenToEncode 函式 (wincrypt.h)

  • 發行項

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

語法

HCRYPTMSG CryptMsgOpenToEncode(
  [in]           DWORD             dwMsgEncodingType,
  [in]           DWORD             dwFlags,
  [in]           DWORD             dwMsgType,
  [in]           void const        *pvMsgEncodeInfo,
  [in, optional] LPSTR             pszInnerContentObjID,
  [in]           PCMSG_STREAM_INFO pStreamInfo
);

參數

[in] dwMsgEncodingType

指定所使用的編碼類型。 將憑證和 訊息編碼類型 與位 OR 作業結合在一起，一律可以接受，如下列範例所示：

X509_ASN_ENCODING |PKCS_7_ASN_ENCODING

目前定義的編碼類型如下：

  • X509_ASN_ENCODING
  • PKCS_7_ASN_ENCODING

[in] dwFlags

下表顯示目前定義的 dwFlags 。

值 意義
CMSG_BARE_CONTENT_FLAG
 串流輸出不會有外部 ContentInfo 包裝函式 (，如 PKCS #7) 所定義。 這可讓您適合串流至封入訊息。
CMSG_DETACHED_FLAG
 後續對 CryptMsgUpdate 的呼叫會提供中斷鏈接的數據。
CMSG_AUTHENTICATED_ATTRIBUTES_FLAG
 如果不需要驗證屬性，則會強制包含在 SignerInfo (中，如 PKCS #7 所定義) 。
CMSG_CONTENTS_OCTETS_FLAG
 用於計算已使用 可辨別編碼規則 (DER) 編碼的訊息大小，且巢狀在信封郵件內。 執行串流時，這特別有用。
CMSG_CMS_ENCAPSULATED_CONTENT_FLAG
 設定時，非數據類型內部內容 會封裝在 OCTET STRING 內。 適用於已簽署和信封的郵件。
CMSG_CRYPT_RELEASE_CONTEXT_FLAG
 如果已設定，則會在最終的 CryptMsgUpdate 上釋放傳遞給此函式的 hCryptProv。 如果函式失敗，則不會釋放句柄。
注意 信封收件者的 hCryptProvs 不會釋出。
 

[in] dwMsgType

指出訊息類型。 這必須是下列其中一個值。

值 意義
CMSG_DATA
 不使用這個值。
CMSG_SIGNED
 pvMsgEncodeInfo 參數是包含編碼資訊的CMSG_SIGNED_ENCODE_INFO結構位址。
CMSG_ENVELOPED
 pvMsgEncodeInfo 參數是包含編碼資訊之CMSG_ENVELOPED_ENCODE_INFO結構的位址。
CMSG_SIGNED_AND_ENVELOPED
 目前未實作此值。
CMSG_HASHED
 pvMsgEncodeInfo 參數是包含編碼資訊之CMSG_HASHED_ENCODE_INFO結構的位址。

[in] pvMsgEncodeInfo

包含編碼資訊之 結構的位址。 數據類型取決於 dwMsgType 參數的值。 如需詳細資訊，請參閱 dwMsgType。

[in, optional] pszInnerContentObjID

如果呼叫 CryptMsgCalculateEncodedLength 且 CryptMsgUpdate 的數據已經編碼訊息，則會在 pszInnerContentObjID 中傳遞適當的對象標識碼 (OID) 。 如果 pszInnerContentObjID 為 NULL，則會假設內部內容類型不是先前編碼，因此會編碼為八進位字串，並指定類型CMSG_DATA。

注意 使用串流時， pszInnerContentObjID 必須是 NULL 或szOID_RSA_data。
 
通常會使用下列演算法 OID。 用戶可以藉由確保訊息的傳送者和接收者同意與 OID 相關聯的語意，來定義新的內部內容使用方式。
  • szOID_RSA_data
  • szOID_RSA_signedData
  • szOID_RSA_envelopedData
  • szOID_RSA_signEnvData
  • szOID_RSA_digestedData
  • szOID_RSA_encryptedData
  • SPC_INDIRECT_DATA_OBJID

[in] pStreamInfo

使用串流時，此參數是 CMSG_STREAM_INFO 結構的位址。 執行 CryptMsgUpdate 時，會呼叫 CMSG_STREAM_INFO 結構的 pfnStreamOutput 成員所指定的回調函式。 回呼會傳遞編碼所產生的編碼位元組。 如需如何使用回呼的詳細資訊，請參閱 CMSG_STREAM_INFO。

注意使用串流時，應用程式不得釋放在 pvMsgEncodeInfo 參數中傳遞的任何數據句柄，例如CMSG_SIGNER_ENCODE_INFO結構 hCryptProv 成員中的提供者句柄，直到使用 CryptMsgClose 函式關閉此函式傳回的訊息句柄之後。
 
未使用串流時，此參數會設定為 NULL。

串流不會與 CMSG_HASHED 訊息類型搭配使用。 處理哈希數據時，此參數必須設定為 NULL。

請考慮封入信封郵件中已簽署郵件的情況。 已簽署訊息摘要之串流編碼的編碼輸出，會轉換成信封郵件的另一個串流編碼。 串流編碼的回呼會呼叫 CryptMsgUpdate 來編碼信封訊息。 信封訊息的回呼會接收巢狀簽署訊息的編碼位元組。

傳回值

如果函式成功，它會傳回已開啟之訊息的句柄。 當不再需要此句柄時，必須將它傳遞至 CryptMsgClose 函式來關閉此句柄。

如果此函式失敗，則會傳回 NULL 。

若要擷取擴充的錯誤資訊，請使用 GetLastError 函 式。

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

傳回碼 Description
CRYPT_E_INVALID_MSG_TYPE
 訊息類型無效。
CRYPT_E_OID_FORMAT
 OID 格式不正確。
CRYPT_E_UNKNOWN_ALGO
 密碼編譯演算法未知。
E_INVALIDARG
 一或多個自變數無效。
E_OUTOFMEMORY
 記憶體不足。
 

此外，如果 dwMsgType 是CMSG_SIGNED，則可以從 CryptCreateHash 傳播錯誤。

如果 dwMsgType 是CMSG_ENVELOPED，則可以從 CryptGenKey、 CryptImportKey 和 CryptExportKey 傳播錯誤。

如果 dwMsgType 是CMSG_HASHED，則可以從 CryptCreateHash 傳播錯誤。

備註

對於執行加密的函式，在內部呼叫 CryptExportKey 之後，加密的對稱密鑰會從位元組端格式反轉為大端格式。 對於執行解密的函式，在呼叫 CryptImportKey 之前，加密的對稱密鑰會從 big-endian 格式反轉為位元組端格式。

當使用 CryptGenKey 和 CryptImportKey 產生和匯入對稱密鑰時，就會指定CRYPT_NO_SALT。

使用 RC2 加密演演算法加密的訊息會搭配 CryptGetKeyParam 使用 KP_EFFECTIVE_KEYLEN，以判斷 RC2 金鑰匯入或匯出密鑰的有效 金鑰長度 。

對於使用 RC2 加密演演算法加密的訊息，已更新編碼和譯碼作業，以處理 CMSG_ENVELOPED_ENCODE_INFO 結構之 ContentEncryptionAlgorithm 成員的 ASN RC2 參數。

對於使用 RC4、DES 和 3DES 加密演算法加密的訊息，編碼和譯碼作業現在會處理 CMSG_ENVELOPED_ENCODE_INFO 結構的 ContentEncryptionAlgorithm 成員的 ASN IV 八位字元串參數。

範例

如需使用此函式的範例，請參閱 範例 C 程式：簽署、編碼、譯碼和驗證訊息、 編碼信封訊息的替代程式代碼、 範例 C 程式：編碼信封、簽署訊息和 範例 C 程式：編碼和譯碼哈希訊息。

規格需求

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

另請參閱

CryptMsgClose

CryptMsgGetParam

CryptMsgOpenToDecode

CryptMsgUpdate

低階訊息函式

簡化的訊息函式