Поделиться через

Функция CryptDecodeObjectEx (wincrypt.h)

  • Статья

Функция CryptDecodeObjectEx декодирует структуру типа, указанного параметром lpszStructType . CryptDecodeObjectEx обеспечивает значительное повышение производительности по сравнению с CryptDecodeObject за счет поддержки выделения памяти со значением CRYPT_DECODE_ALLOC_FLAG.

Синтаксис

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

Используемый тип кодирования. Всегда допустимо указывать типы кодированиясертификатов и сообщений, объединяя их с побитовой операцией ИЛИ, как показано в следующем примере:

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

Этот параметр может быть одним или несколькими из следующих флагов. Флаги можно объединить с помощью побитовой операции ИЛИ .

Значение Значение
CRYPT_DECODE_ALLOC_FLAG
 Вызываемая функция декодирования выделяет память для декодированных структур. Указатель на выделенную структуру возвращается в pvStructInfo.

Если pDecodePara или член pfnAllocpDecodePara имеет значение NULL, то для выделения вызывается LocalAlloc , а для освобождения памяти необходимо вызвать LocalFree .

Если pDecodePara и член pfnAllocpDecodePara не имеют значения NULL, то функция, на которую указывает pfnAlloc , вызывается для выделения, а функция, на которую указывает член pfnFreepDecodePara , должна быть вызвана для освобождения памяти.
CRYPT_DECODE_ENABLE_PUNYCODE_FLAG
33554432 (0x2000000)
 Этот флаг применим для включения декодирования строковых значений Юникода в Punycode. Дополнительные сведения см. в подразделе "Примечания".

Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Этот флаг не поддерживается.
CRYPT_DECODE_NOCOPY_FLAG
 Этот флаг можно установить, чтобы включить оптимизацию "без копирования". Эта оптимизация обновляет члены pvStructInfo , чтобы они указывали на содержимое, которое находится в pbEncoded , а не создавать копию содержимого и добавлять его в pvStructInfo. Вызывающему приложению требуется выделить меньше памяти, и выполнение выполняется быстрее, так как копирование не выполняется. Обратите внимание, что при выполнении декодирования "без копирования" pbEncoded не может быть освобожден до освобождения pvStructInfo .
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

Если задан CRYPT_ENCODE_ALLOC_FLAG dwFlags , pvStructInfo не является указателем на буфер, а адресом указателя на буфер. Так как память выделяется внутри функции, а указатель хранится в *pvStructInfo, pvStructInfo никогда не должен иметь значение NULL.

Если CRYPT_ENCODE_ALLOC_FLAG не задано, pvStructInfo является указателем на буфер, который получает декодированную структуру. Если указанный буфер недостаточно велик для получения декодированных структур, функция задает код ERROR_MORE_DATA и сохраняет требуемый размер буфера в байтах в переменной, на которую указывает pcbStructInfo.

Этот параметр может иметь значение NULL , чтобы получить размер этих сведений для целей выделения памяти. Дополнительные сведения см. в разделе Извлечение данных неизвестной длины.

[in, out] pcbStructInfo

Указатель на переменную DWORD , содержащую размер (в байтах) буфера, на который указывает параметр pvStructInfo . Когда функция возвращает значение DWORD , содержит количество байтов, хранящихся в буфере. Размер, содержащийся в переменной, на которую указывает pcbStructInfo , может указывать на размер, превышающий декодированную структуру, так как декодированная структура может включать указатели на вспомогательные данные. Этот размер представляет собой сумму размера, необходимого для декодированных структур и вспомогательных данных.

Если задано CRYPT_DECODE_ALLOC_FLAG, начальное значение *pcbStructInfo не используется функцией, а при возврате *pcbStructInfo содержит количество байтов, выделенных для pvStructInfo.

Примечание При обработке данных, возвращаемых в буфере, приложения должны использовать фактический размер возвращаемых данных. Фактический размер может быть немного меньше размера буфера, указанного во входных данных. (На входных данных размеры буфера обычно указываются достаточно большими, чтобы убедиться, что максимально возможные выходные данные помещаются в буфер.) В выходных данных переменная, на которую указывает этот параметр, обновляется с учетом фактического размера данных, скопированных в буфер.
 

Возвращаемое значение

Если функция выполняется успешно, функция возвращает ненулевое значение (TRUE).

Если функция завершается сбоем, она возвращает ноль (FALSE). Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError. В следующей таблице показаны некоторые возможные коды ошибок.

Код возврата Описание
CRYPT_E_BAD_ENCODE
 Во время декодирования произошла ошибка.
ERROR_FILE_NOT_FOUND
 Не удалось найти функцию декодирования для указанных dwCertEncodingType и lpszStructType.
ERROR_MORE_DATA
 Если буфер, заданный параметром pvStructInfo , недостаточно велик для хранения возвращаемых данных, функция задает код ERROR_MORE_DATA и сохраняет требуемый размер буфера в байтах в переменной, на которую указывает pcbStructInfo.
 

В случае сбоя функции 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 в сочетании со значением члена dwAltNameChoice структуры CERT_ALT_NAME_ENTRY определяет способ кодирования строк.
dwAltNameChoice Действие
CERT_ALT_NAME_DNS_NAME Если имя узла содержит строку IA5String в кодировке Punycode, она преобразуется в эквивалент Юникода.
CERT_ALT_NAME_RFC822_NAME Если часть имени узла адреса электронной почты содержит строку IA5String в кодировке Punycode, она преобразуется в эквивалент Юникода.
CERT_ALT_NAME_URL Декодируется универсальный код ресурса (URI). Если имя узла сервера URI содержит строку IA5String в кодировке Punycode, строка имени узла декодируется в эквивалент юникода.
 

Каждая константа в приведенном ниже списке имеет связанный тип структуры, на который указывает параметр pvStructInfo . Прямо или косвенно указанная структура имеет ссылку на CERT_HASHED_URL структуру.

  • szOID_LOGOTYPE_EXT
  • X509_LOGOTYPE_EXT
  • szOID_BIOMETRIC_EXT
  • X509_BIOMETRIC_EXT
При декодировании значения структуры CERT_HASHED_URL декодируется универсальный код ресурса (URI). Если имя узла содержит имя узла в кодировке Punycode, оно преобразуется в эквивалент Юникода.

Каждая константа X509_UNICODE_NAME в приведенном ниже списке имеет связанный тип структуры, на который указывает параметр pvStructInfo .

  • X509_UNICODE_NAME
Если для элемента pszObjId структуры CERT_RDN_ATTR задано значение szOID_RSA_emailAddr , а адрес электронной почты в элементе Value содержит строку в кодировке Punycode, он преобразуется в эквивалент Юникода.

Примеры

Пример использования этой функции см. в разделе Пример программы C: кодирование и декодирование ASN.1.

Требования

   
Минимальная версия клиента Windows XP [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2003 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header wincrypt.h
Библиотека Crypt32.lib
DLL Crypt32.dll

См. также раздел

CryptDecodeObject

CryptEncodeObject

CryptEncodeObjectEx

Функции кодирования и декодирования объектов