CryptDecodeObjectEx 函式 (wincrypt.h)

發行項
08/27/2023

CryptDecodeObjectEx函式會解碼lpszStructType參數所指示之型別的結構。 CryptDecodeObjectEx 藉由使用 CRYPT_DECODE_ALLOC_FLAG 值支援記憶體配置，藉此大幅改善 CryptDecodeObject 的效能。

語法

BOOL CryptDecodeObjectEx(
  [in]      DWORD              dwCertEncodingType,
  [in]      LPCSTR             lpszStructType,
  [in]      const BYTE         *pbEncoded,
  [in]      DWORD              cbEncoded,
  [in]      DWORD              dwFlags,
  [in]      PCRYPT_DECODE_PARA pDecodePara,
  [out]     void               *pvStructInfo,
  [in, out] DWORD              *pcbStructInfo
);

參數

[in] dwCertEncodingType

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

X509_ASN_ENCODING |PKCS_7_ASN_ENCODING

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

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

注意需要憑證或訊息編碼類型。 X509_ASN_ENCODING是預設值。如果指出該類型，則會使用它。否則，如果指出PKCS7_ASN_ENCODING類型，則會使用它。

[in] lpszStructType

定義結構類型的物件識別碼指標 (OID) 。如果 lpszStructType 參數的高序字是零，則低序字會指定指定結構類型的整數識別碼。否則，此參數是 Null 終止字串的長指標。

如需物件識別碼字串、其預先定義的常數和對應的結構的詳細資訊，請參閱 CryptEncodeObject 和 CryptDecodeObject 的常數。

[in] pbEncoded

要解碼之資料的指標。結構必須是 lpszStructType所指定的類型。

[in] cbEncoded

pbEncoded所指向的位元組數目。這是要解碼的位元組數目。

[in] dwFlags

此參數可以是下列一或多個旗標。旗標可以使用位OR 運算來結合。

值	意義
CRYPT_DECODE_ALLOC_FLAG	呼叫的解碼函式會配置已解碼結構的記憶體。配置結構的指標會在 pvStructInfo中傳回。如果pDecodePara 或 pDecodePara的pfnAlloc成員為Null，則會針對配置呼叫LocalAlloc，而且必須呼叫LocalFree以釋放記憶體。如果pDecodePara 和 pDecodePara的pfnAlloc成員不是Null，則會針對配置呼叫pfnAlloc所指向的函式，而且必須呼叫pDecodePara的pfnFree成員所指向的函式來釋放記憶體。
CRYPT_DECODE_ENABLE_PUNYCODE_FLAG 33554432 (0x2000000)	此旗標適用于啟用 Unicode 字串值的 Punycode 解碼。如需詳細資訊，請參閱＜備註＞。 Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP：不支援此旗標。
CRYPT_DECODE_NOCOPY_FLAG	這個旗標可以設定為啟用「沒有複製」優化。此優化會更新 pvStructInfo 成員，以指向位於 pbEncoded 內的內容，而不是複製內容，並將它附加至 pvStructInfo。呼叫的應用程式需要配置較少的記憶體，而且執行速度較快，因為不會進行複本。請注意，在執行「無複製」解碼時，除非釋放 pvStructInfo，否則無法釋放pbEncoded。
CRYPT_UNICODE_NAME_DECODE_DISABLE_IE4_UTF8_FLAG	解碼X509_UNICODE_NAME、X509_UNICODE_NAME_VALUE或X509_UNICODE_ANY_STRING時，適用此旗標。根據預設，CERT_RDN_T61_STRING編碼的值一開始會解碼為 UTF8。如果 UTF8 解碼失敗，則會將值解碼為八位字元。如果設定此旗標，它會略過將值解碼為 UTF8 的初始嘗試，並將值解碼為八位字元。
CRYPT_DECODE_TO_BE_SIGNED_FLAG	根據預設， pbEncoded 所指向之緩衝區的內容包含已簽署的內容和簽章。如果設定此旗標，緩衝區只會包含「要簽署」的內容。此旗標適用于X509_CERT_TO_BE_SIGNED、X509_CERT_CRL_TO_BE_SIGNED、X509_CRT_REQUEST_TO_BE_SIGNED和X509_KEYGEN_REQUEST_TO_BE_SIGNED物件。
CRYPT_DECODE_SHARE_OID_STRING_FLAG	設定此旗標時，OID 字串會配置在 Crypt32.dll 中，並共用，而不是複製到傳回的資料結構中。如果在卸載呼叫端之前未卸載 Crypt32.dll，可以設定此旗標。
CRYPT_DECODE_NO_SIGNATURE_BYTE_REVERSAL_FLAG	根據預設，簽章位元組會反轉。如果設定此旗標，則會禁止此位元組反轉。

[in] pDecodePara

包含解碼段落資訊的 CRYPT_DECODE_PARA 結構的指標。如果 pDecodePara 設定為 Null，則會使用 LocalAlloc 和 LocalFree 來配置和釋放記憶體。如果 pDecodePara 指向 CRYPT_DECODE_PARA 結構，該結構會傳入回呼函式來配置和釋放記憶體。這些回呼函式會覆寫 LocalAlloc 和 LocalFree的預設記憶體配置。

[out] pvStructInfo

如果 已設定 dwFlags CRYPT_ENCODE_ALLOC_FLAG， pvStructInfo 不是緩衝區的指標，而是緩衝區指標的位址。因為記憶體配置在函式內，而且指標儲存在 *pvStructInfo， pvStructInfo 絕對不能是 Null。

如果未設定CRYPT_ENCODE_ALLOC_FLAG， pvStructInfo 是接收解碼結構的緩衝區指標。當指定的緩衝區不夠大，無法接收解碼的結構時，函式會設定ERROR_MORE_DATA程式碼，並以位元組為單位儲存所需的緩衝區大小，以位元組為單位，以位元組為單位儲存 在由tructInfo所指向的變數中。

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

[in, out] pcbStructInfo

DWORD變數的指標，其中包含pvStructInfo參數所指向之緩衝區的大小，以位元組為單位。當函式傳回時， DWORD 值會包含儲存在緩衝區中的位元組數目。 由{structInfo指向的變數中包含的大小可以指出大於解碼結構的大小，因為解碼的結構可以包含輔助資料的指標。此大小是解碼結構和輔助資料所需的大小總和。

設定CRYPT_DECODE_ALLOC_FLAG時，函式不會使用 *wifiStructInfo 的初始值，而且在傳回時，*wifiStructInfo 包含配置給 pvStructInfo的位元組數目。

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

傳回值

如果函式成功，函式會傳回非零 (TRUE) 。

如果函式失敗，它會傳回零 (FALSE) 。如需擴充錯誤資訊，請呼叫 GetLastError。下表顯示一些可能的錯誤碼。

傳回碼	描述
CRYPT_E_BAD_ENCODE	解碼時發生錯誤。
ERROR_FILE_NOT_FOUND	找不到指定 dwCertEncodingType 和 lpszStructType的解碼函式。
ERROR_MORE_DATA	如果 pvStructInfo 參數指定的緩衝區不夠大，無法保存傳回的資料，則函式會設定ERROR_MORE_DATA程式碼，並將所需的緩衝區大小以位元組為單位儲存在以 mb為單位的變數中。

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

備註

使用慣用 CryptEncodeObjectEx 函式編碼密碼編譯物件時，會包含終止 的 Null 字元。解碼時，使用慣用 的 CryptDecodeObjectEx 函式，不會保留終止 的 Null 字元。

下列清單中的每個常數都有 pvStructInfo 參數所指向的相關聯結構類型。直接或間接指向的結構具有 CERT_ALT_NAME_ENTRY 結構的參考。

X509_ALTERNATE_NAME
szOID_AUTHORITY_INFO_ACCESS
X509_AUTHORITY_INFO_ACCESS
X509_AUTHORITY_KEY_ID2
szOID_AUTHORITY_KEY_IDENTIFIER2
szOID_CRL_DIST_POINTS
X509_CRL_DIST_POINTS
szOID_CROSS_CERT_DIST_POINTS
X509_CROSS_CERT_DIST_POINTS
szOID_ISSUER_ALT_NAME
szOID_ISSUER_ALT_NAME2
szOID_ISSUING_DIST_POINT
X509_ISSUING_DIST_POINT
X509_NAME_CONSTRAINTS
szOID_NAME_CONSTRAINTS
szOID_NEXT_UPDATE_LOCATION
OCSP_REQUEST
zOID_SUBJECT_ALT_NAME
szOID_SUBJECT_ALT_NAME2

CRYPT_DECODE_ENABLE_PUNYCODE_FLAG旗標與CERT_ALT_NAME_ENTRY結構dwAltNameChoice成員的值一起決定字串編碼的方式。

dwAltNameChoice	效果
CERT_ALT_NAME_DNS_NAME	如果主機名稱包含 Punycode 編碼的 IA5String 字串，則會轉換成 Unicode 對等專案。
CERT_ALT_NAME_RFC822_NAME	如果電子郵件地址的主機名稱部分包含 Punycode 編碼的 IA5String 字串，則會轉換成其 Unicode 對等專案。
CERT_ALT_NAME_URL	URI 已解碼。如果 URI 的伺服器主機名稱包含 Punycode 編碼的 IA5String 字串，主機名稱字串會解碼為 Unicode 對等專案。

下列清單中的每個常數都有一個相關聯的結構類型，由 pvStructInfo 參數所指向。直接或間接指向的結構具有 CERT_HASHED_URL 結構的參考。

szOID_LOGOTYPE_EXT
X509_LOGOTYPE_EXT
szOID_BIOMETRIC_EXT
X509_BIOMETRIC_EXT

解碼 CERT_HASHED_URL 結構值時，會解碼 URI。如果主機名稱包含 Punycode 編碼的主機名稱，則會轉換成 Unicode 對等專案。

下列清單中的每個 X509_UNICODE_NAME 常數都有 pvStructInfo 參數指向的相關聯結構類型。

X509_UNICODE_NAME

如果CERT_RDN_ATTR結構的pszObjId成員設定為szOID_RSA_emailAddr，而 Value成員中的電子郵件地址包含 Punycode 編碼字串，則會轉換成 Unicode 對等專案。

範例

如需使用此函式的範例，請參閱範例 C 程式：ASN.1 編碼和解碼。

規格需求


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

另請參閱

共用方式為

CryptDecodeObjectEx 函式 (wincrypt.h)

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

其他資源