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 解码失败，则将该值解码为 8 位字符。如果设置了此标志，它将跳过将值解码为 UTF8 的初始尝试，并将该值解码为 8 位字符。
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代码，并将所需的缓冲区大小（以字节为单位）存储在 由ERROR_MORE_DATA号指向的变量中。

此参数可为 NULL ，用于检索此信息的大小，以便进行内存分配。有关详细信息，请参阅检索未知长度的数据。

[in, out] pcbStructInfo

指向 DWORD 变量的指针，该变量包含 pvStructInfo 参数指向的缓冲区的大小（以字节为单位）。当函数返回时， DWORD 值包含缓冲区中存储的字节数。由于解码的结构可以包含指向辅助数据的指针， 因此，由代码 指向的变量中包含的大小可以指示大于已解码结构的大小。此大小是解码结构和辅助数据所需的大小之和。

设置CRYPT_DECODE_ALLOC_FLAG时，函数不使用初始值 *bstructInfo ，返回时，*CRYPT_DECODE_ALLOC_FLAG 包含为 pvStructInfo 分配的字节数。

注意处理缓冲区中返回的数据时，应用程序必须使用返回的数据的实际大小。实际大小可以略小于输入时指定的缓冲区的大小。 (输入时，缓冲区大小通常指定得足够大，以确保最大输出数据适合 buffer。) 输出时，此参数指向的变量将更新，以反映复制到缓冲区的数据的实际大小。

返回值

如果函数成功，则函数) 返回非零 (TRUE 。

如果函数失败，它将返回零 (FALSE) 。有关扩展的错误信息，请调用 GetLastError。下表显示了一些可能的错误代码。

返回代码	说明
CRYPT_E_BAD_ENCODE	解码时遇到错误。
ERROR_FILE_NOT_FOUND	找不到指定 dwCertEncodingType 和 lpszStructType 的解码函数。
ERROR_MORE_DATA	如果 pvStructInfo 参数指定的缓冲区不够大，无法容纳返回的数据，该函数将设置ERROR_MORE_DATA代码，并将所需的缓冲区大小（以字节为单位）存储在由ERROR_MORE_DATA号指向的变量中。

如果函数失败， GetLastError 可能会返回抽象语法表示法 One (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
Library	Crypt32.lib
DLL	Crypt32.dll

另请参阅

CryptDecodeObjectEx 函数 (wincrypt.h)

语法

参数

返回值

注解

示例

要求

另请参阅

反馈

反馈

其他资源