Функция 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
[in] lpszStructType
Указатель на идентификатор объекта (OID), определяющий тип структуры. Если слово высокого порядка параметра lpszStructType равно нулю, слово низкого порядка задает целочисленный идентификатор для типа указанной структуры. В противном случае этот параметр является длинным указателем на строку, завершаемую null.
Дополнительные сведения о строках идентификаторов объектов, их предопределенных константах и соответствующих структурах см. в разделе Константы для CryptEncodeObject и CryptDecodeObject.
[in] pbEncoded
Указатель на декодированные данные. Структура должна иметь тип, заданный lpszStructType.
[in] cbEncoded
Число байтов, на которые указывает pbEncoded. Это число декодированных байтов.
[in] dwFlags
Этот параметр может быть одним или несколькими из следующих флагов. Флаги можно объединить с помощью побитовой операции ИЛИ .
| Значение | Значение |
|---|---|
|
Вызываемая функция декодирования выделяет память для декодированных структур. Указатель на выделенную структуру возвращается в pvStructInfo.
Если pDecodePara или член pfnAllocpDecodePara имеет значение NULL, то для выделения вызывается LocalAlloc , а для освобождения памяти необходимо вызвать LocalFree . Если pDecodePara и член pfnAllocpDecodePara не имеют значения NULL, то функция, на которую указывает pfnAlloc , вызывается для выделения, а функция, на которую указывает член pfnFreepDecodePara , должна быть вызвана для освобождения памяти. |
|
Этот флаг применим для включения декодирования строковых значений Юникода в Punycode. Дополнительные сведения см. в подразделе "Примечания".
Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Этот флаг не поддерживается. |
|
Этот флаг можно установить, чтобы включить оптимизацию "без копирования". Эта оптимизация обновляет члены pvStructInfo , чтобы они указывали на содержимое, которое находится в pbEncoded , а не создавать копию содержимого и добавлять его в pvStructInfo. Вызывающему приложению требуется выделить меньше памяти, и выполнение выполняется быстрее, так как копирование не выполняется. Обратите внимание, что при выполнении декодирования "без копирования" pbEncoded не может быть освобожден до освобождения pvStructInfo . |
|
Этот флаг применим при декодировании X509_UNICODE_NAME, X509_UNICODE_NAME_VALUE или X509_UNICODE_ANY_STRING. По умолчанию CERT_RDN_T61_STRING закодированные значения изначально декодируются как UTF8. Если декодирование UTF8 завершается сбоем, значение декодируется как восьмибитовые символы. Если этот флаг установлен, он пропускает начальную попытку декодировать значение как UTF8 и декодирует значение в виде восьми битовых символов. |
|
По умолчанию содержимое буфера, на который указывает pbEncoded, включало подписанное содержимое и подпись. Если этот флаг установлен, буфер содержит только содержимое "для подписи". Этот флаг применим к объектам X509_CERT_TO_BE_SIGNED, X509_CERT_CRL_TO_BE_SIGNED, X509_CRT_REQUEST_TO_BE_SIGNED и X509_KEYGEN_REQUEST_TO_BE_SIGNED. |
|
Если этот флаг установлен, строки OID выделяются в Crypt32.dll и совместно используются вместо копирования в возвращаемую структуру данных. Этот флаг можно установить, если Crypt32.dll не выгружается до выгрузки вызывающего объекта. |
|
По умолчанию байты подписи отменяются. Если этот флаг установлен, этот разворот байтов блокируется. |
[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. В следующей таблице показаны некоторые возможные коды ошибок.
| Код возврата | Описание |
|---|---|
|
Во время декодирования произошла ошибка. |
|
Не удалось найти функцию декодирования для указанных dwCertEncodingType и lpszStructType. |
|
Если буфер, заданный параметром 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
| 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
Каждая константа X509_UNICODE_NAME в приведенном ниже списке имеет связанный тип структуры, на который указывает параметр pvStructInfo .
- X509_UNICODE_NAME
Примеры
Пример использования этой функции см. в разделе Пример программы C: кодирование и декодирование ASN.1.
Требования
| Минимальная версия клиента | Windows XP [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | wincrypt.h |
| Библиотека | Crypt32.lib |
| DLL | Crypt32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по