CryptMsgGetParam 函式 (wincrypt.h)

發行項
08/27/2023

CryptMsgGetParam函式會在密碼編譯訊息編碼或解碼之後取得訊息參數。此函式會在最終的 CryptMsgUpdate 呼叫之後呼叫。

語法

BOOL CryptMsgGetParam(
  [in]      HCRYPTMSG hCryptMsg,
  [in]      DWORD     dwParamType,
  [in]      DWORD     dwIndex,
  [out]     void      *pvData,
  [in, out] DWORD     *pcbData
);

參數

[in] hCryptMsg

密碼編譯訊息的控制碼。

[in] dwParamType

指出要擷取之資料的參數類型。要擷取的資料類型會決定要用於 pvData的結構類型。

針對編碼的訊息，只有 CMSG_BARE_CONTENT、CMSG_ENCODE_SIGNER、CMSG_CONTENT_PARAM 和 CMSG_COMPUTED_HASH_PARAM dwParamTypes 有效。

值	意義
CMSG_ATTR_CERT_COUNT_PARAM	pvData資料類型：DWORD的指標傳回 SIGNED 或 ENVELOPED 訊息中屬性憑證的計數。
CMSG_ATTR_CERT_PARAM	pvData 資料類型： BYTE 陣列的指標擷取屬性憑證。若要取得所有屬性憑證，請呼叫 CryptMsgGetParam 不同的 dwIndex 設定為 0 個屬性數目減一。
CMSG_BARE_CONTENT_PARAM	pvData 資料類型： BYTE 陣列的指標擷取編碼密碼編譯訊息的編碼內容，而不需要CONTENT_INFO結構的外部層。也就是說，只會傳回 PKCS #7 定義 ContentInfo.content 欄位的編碼方式。
CMSG_CERT_COUNT_PARAM	pvData資料類型：DWORD的指標傳回所接收 SIGNED 或 ENVELOPED 訊息中的憑證數目。
CMSG_CERT_PARAM	pvData 資料類型： BYTE 陣列的指標傳回簽署者的憑證。若要取得所有簽署者的憑證，請呼叫 CryptMsgGetParam，將 dwIndex 從 0 變更為可用憑證數目減一。
CMSG_COMPUTED_HASH_PARAM	pvData 資料類型： BYTE 陣列的指標傳回訊息中資料計算的雜湊。此類型適用于編碼和解碼。
CMSG_CONTENT_PARAM	pvData 資料類型： BYTE 陣列的指標從開啟要編碼的訊息傳回整個 PKCS #7 訊息。擷取開啟以解碼之訊息的內部內容。如果郵件是信封的，內部類型是資料，而且已呼叫 CryptMsgControl 來解密訊息，則會傳回解密的內容。如果內部類型不是資料，則會傳回需要進一步解碼的編碼 BLOB。如果訊息未封迭，且內部內容為 DATA，則傳回的資料是內部內容的八位。此類型適用于編碼和解碼。若為解碼，如果類型為CMSG_DATA，則會傳回內容的八位;否則會傳回編碼的內部內容。
CMSG_CRL_COUNT_PARAM	pvData資料類型：DWORD的指標傳回已接收、SIGNED 或 ENVELOPED 訊息中的 CRL 計數。
CMSG_CRL_PARAM	pvData 資料類型： BYTE 陣列的指標傳回 CRL。若要取得所有 CRL，請呼叫 CryptMsgGetParam，將 dwIndex 從 0 變更為可用 CRL 數目減一。
CMSG_ENCODED_MESSAGE	pvData 資料類型： BYTE 陣列的指標變更已編碼訊息的內容。訊息必須先以對 CryptMsgOpenToDecode的呼叫進行解碼。然後，透過對CryptMsgControl、CryptMsgCountersign 或 CryptMsgCountersignEncoded的呼叫來變更訊息。訊息接著會再次編碼，並呼叫 CryptMsgGetParam，並指定CMSG_ENCODED_MESSAGE以取得反映所做的變更的新編碼方式。例如，這可用來將時間戳記屬性新增至訊息。
CMSG_ENCODED_SIGNER	pvData 資料類型： BYTE 陣列的指標傳回訊息簽署者的編碼CMSG_SIGNER_INFO簽署者資訊。
CMSG_ENCRYPTED_DIGEST	pvData 資料類型： BYTE 陣列的指標傳回簽章的加密雜湊。通常用於執行時間戳記。
CMSG_ENCRYPT_PARAM	pvData資料類型：CRYPT_ALGORITHM_IDENTIFIER 結構的BYTE陣列指標。傳回用來加密訊息的加密演算法。
CMSG_ENVELOPE_ALGORITHM_PARAM	pvData資料類型：CRYPT_ALGORITHM_IDENTIFIER 結構的BYTE陣列指標。傳回用來加密 ENVELOPED 訊息的加密演算法。
CMSG_HASH_ALGORITHM_PARAM	pvData資料類型：CRYPT_ALGORITHM_IDENTIFIER 結構的BYTE陣列指標。傳回用來在建立訊息時雜湊訊息的雜湊演算法。
CMSG_HASH_DATA_PARAM	pvData 資料類型： BYTE 陣列的指標傳回建立訊息時儲存在訊息中的雜湊值。
CMSG_INNER_CONTENT_TYPE_PARAM	pvData 資料類型： BYTE 陣列的指標，以接收 null終止的物件識別碼 (OID) 字串。傳回所接收訊息的內部內容類型。此類型不適用於 DATA 類型的訊息。
CMSG_RECIPIENT_COUNT_PARAM	pvData資料類型：DWORD的指標傳回 ENVELOPED 接收郵件的金鑰傳輸收件者數目。
CMSG_CMS_RECIPIENT_COUNT_PARAM	pvData資料類型：DWORD的指標傳回所有郵件收件者的總計數，包括金鑰合約和郵寄清單收件者。
CMSG_RECIPIENT_INDEX_PARAM	pvData資料類型：DWORD的指標傳回用來解密 ENVELOPED 訊息之金鑰傳輸收件者的索引。只有在訊息解密之後，才能使用此值。
CMSG_CMS_RECIPIENT_INDEX_PARAM	pvData資料類型：DWORD的指標傳回用來解密 ENVELOPED 郵件的金鑰傳輸、金鑰合約或郵寄清單收件者的索引。
CMSG_CMS_RECIPIENT_ENCRYPTED_KEY_INDEX_PARAM	pvData資料類型：DWORD的指標傳回用來解密 ENVELOPED 訊息之金鑰合約收件者之加密金鑰的索引。
CMSG_RECIPIENT_INFO_PARAM	pvData 資料類型： BYTE 陣列的指標，以接收 CERT_INFO 結構。傳回金鑰傳輸訊息收件者的相關憑證資訊。若要取得所有金鑰傳輸訊息收件者的憑證資訊，請重複呼叫 CryptMsgGetParam，將 dwIndex 從 0 變更為收件者數目減一。只有傳回之CERT_INFO 結構的 Issuer、SerialNumber 和 PublicKeyAlgorithm 成員可用且有效。
CMSG_CMS_RECIPIENT_INFO_PARAM	pvData 資料類型： BYTE 陣列的指標，以接收 CMSG_CMS_RECIPIENT_INFO 結構。傳回金鑰傳輸、金鑰合約或郵寄清單收件者的相關資訊。它不限於金鑰傳輸郵件收件者。若要取得所有郵件收件者的資訊，請重複呼叫 CryptMsgGetParam，將 dwIndex 從 0 變更為收件者數目減一。
CMSG_SIGNER_AUTH_ATTR_PARAM	pvData 資料類型： BYTE 陣列的指標，以接收 CRYPT_ATTRIBUTES 結構。傳回訊息簽署者的已驗證屬性。若要擷取指定之簽署者的已驗證屬性，請使用dwIndex等於該簽署者的索引呼叫CryptMsgGetParam。
CMSG_SIGNER_CERT_INFO_PARAM	pvData 資料類型： BYTE 陣列的指標，以接收 CERT_INFO 結構。傳回識別簽署者憑證所需的訊息簽署者資訊。憑證的簽發者和 SerialNumber 可用來唯一識別要擷取的憑證。若要擷取所有簽署者的資訊，請重複呼叫 CryptMsgGetParam 從 0 到簽署者數目減一的 dwIndex 。只有傳回之CERT_INFO 結構中的 Issuer 和 SerialNumber 欄位包含可用的有效資料。
CMSG_SIGNER_CERT_ID_PARAM	pvData 資料類型： BYTE 陣列的指標，以接收 CERT_ID 結構。傳回識別簽署者公開金鑰所需的訊息簽署者資訊。這可能是憑證的簽發者和 SerialNumber、KeyID 或 HashId。若要擷取所有簽署者的資訊，請呼叫 CryptMsgGetParam 從 0 到簽署者數目減一的 dwIndex 。
CMSG_SIGNER_COUNT_PARAM	pvData資料類型：DWORD的指標傳回已接收 SIGNED 訊息的簽署者數目。
CMSG_SIGNER_HASH_ALGORITHM_PARAM	pvData 資料類型： BYTE 陣列的指標，以接收 CRYPT_ALGORITHM_IDENTIFIER 結構。傳回訊息簽署者所使用的雜湊演算法。若要取得指定之簽署者的雜湊演算法，請使用dwIndex等於該簽署者的索引呼叫CryptMsgGetParam。
CMSG_SIGNER_INFO_PARAM	pvData 資料類型： BYTE 陣列的指標，以接收 CMSG_SIGNER_INFO 結構。傳回訊息簽署者的資訊。這包括簽署者憑證的簽發者和序號，以及簽署者憑證的已驗證和未驗證屬性。若要擷取訊息的所有簽署者資訊，請呼叫 CryptMsgGetParam 從 0 到簽署者數目減一的 dwIndex 。
CMSG_CMS_SIGNER_INFO_PARAM	pvData 資料類型： BYTE 陣列的指標，以接收 CMSG_CMS_SIGNER_INFO 結構。傳回訊息簽署者的資訊。這包括 signerId 和已驗證和未驗證的屬性。若要擷取訊息的所有簽署者資訊，請呼叫 CryptMsgGetParam 從 0 到簽署者數目減一的 dwIndex 。
CMSG_SIGNER_UNAUTH_ATTR_PARAM	pvData 資料類型： BYTE 陣列的指標，以接收 CRYPT_ATTRIBUTES 結構。傳回訊息簽署者的未驗證屬性。若要擷取指定之簽署者的未驗證屬性，請使用dwIndex等於該簽署者的索引呼叫CryptMsgGetParam。
CMSG_TYPE_PARAM	pvData資料類型：DWORD的指標傳回未知型別之解碼訊息的訊息類型。擷取的訊息類型可以與支援的型別進行比較，以判斷是否可以繼續處理。如需支援的訊息類型，請參閱CryptMsgOpenToDecode的dwMessageType參數。
CMSG_UNPROTECTED_ATTR_PARAM	pvData 資料類型： BYTE 陣列的指標，以接收 CMSG_ATTR 結構。傳回信封訊息中未受保護的屬性。
CMSG_VERSION_PARAM	pvData資料類型：DWORD的指標傳回解碼訊息的版本。如需詳細資訊，請參閱＜備註＞一節中的表格。

[in] dwIndex

所擷取之參數的索引，如果適用的話。未擷取參數時，會忽略此參數，並將設定為零。

[out] pvData

接收所擷取資料的緩衝區指標。此資料的格式會根據 dwParamType 參數的值而有所不同。

此參數可以是 Null ，可針對記憶體配置目的設定此資訊的大小。如需詳細資訊，請參閱擷取未知長度的資料。

處理此緩衝區中傳回的資料時，應用程式必須使用傳回之資料的實際大小。實際大小可能比輸入上指定的緩衝區大小稍微小一點。 (輸入時，通常會指定足夠的緩衝區大小，以確保最大可能的輸出資料會符合 buffer.) On 輸出中，此參數所指向的變數會更新，以反映複製到緩衝區的資料的實際大小。

[in, out] pcbData

變數的指標，指定 pvData 參數所指向之緩衝區的大小，以位元組為單位。當函式傳回時，由其所指向的變數會包含儲存在緩衝區中的位元組數目。

傳回值

如果函式成功，則傳回值為非零 (TRUE) 。

如果函式失敗，則傳回值為零， (FALSE) 。如需擴充錯誤資訊，請呼叫 GetLastError。

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

傳回碼	描述
CRYPT_E_ATTRIBUTES_MISSING	訊息不包含所要求的屬性。
CRYPT_E_INVALID_INDEX	索引值無效。
CRYPT_E_INVALID_MSG_TYPE	訊息類型無效。
CRYPT_E_NOT_DECRYPTED	尚未解密訊息內容。
CRYPT_E_OID_FORMAT	物件識別碼的格式不正確。
CRYPT_E_UNEXPECTED_ENCODING	訊息未如預期編碼。
E_INVALIDARG	一或多個引數無效。
ERROR_MORE_DATA	指定的緩衝區不夠大，無法保存傳回的資料。

針對 dwParamType CMSG_COMPUTED_HASH_PARAM，可以從 CryptGetHashParam傳播錯誤。

如果函式失敗， GetLastError 可能會傳回抽象語法標記法一 (ASN.1) 編碼/解碼錯誤。如需這些錯誤的相關資訊，請參閱 ASN.1 編碼/解碼傳回值。

備註

下列版本號碼是透過呼叫 CryptMsgGetParam ，並將 dwParamType 設定為 CMSG_VERSION_PARAM 定義：

CMSG_SIGNED_DATA_V1
CMSG_SIGNED_DATA_V3
CMSG_SIGNED_DATA_PKCS_1_5_VERSION
CMSG_SIGNED_DATA_CMS_VERSION
CMSG_SIGNER_INFO_V1
CMSG_SIGNER_INFO_V3
CMSG_SIGNER_INFO_PKCS_1_5_VERSION
CMSG_SIGNER_INFO_CMS_VERSION
CMSG_HASHED_DATA_V0
CMSG_HASHED_DATA_V2
CMSG_HASHED_DATA_PKCS_1_5_VERSION
CMSG_HASHED_DATA_CMS_VERSION
CMSG_ENVELOPED_DATA_V0
CMSG_ENVELOPED_DATA_V2
CMSG_ENVELOPED_DATA_PKCS_1_5_VERSION
CMSG_ENVELOPED_DATA_CMS_VERSION

範例

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

規格需求


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