CertGetCertificateContextProperty function (wincrypt.h)

  • Статья

Функция CertGetCertificateContextProperty извлекает сведения, содержащиеся в расширенном свойстве контекста сертификата.

Синтаксис

BOOL CertGetCertificateContextProperty(
  [in]      PCCERT_CONTEXT pCertContext,
  [in]      DWORD          dwPropId,
  [out]     void           *pvData,
  [in, out] DWORD          *pcbData
);

Параметры

[in] pCertContext

Указатель на CERT_CONTEXT структуру сертификата , содержащего извлекаемое свойство.

[in] dwPropId

Извлекаемое свойство. В следующей таблице перечислены текущие идентификаторы и тип данных, возвращаемых в pvData .

CERT_ACCESS_STATE_PROP_ID

Тип данных pvData: указатель на значение DWORD .

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

CERT_AIA_URL_RETRIEVED_PROP_ID

Этот идентификатор зарезервирован.

CERT_ARCHIVED_KEY_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает ранее сохраненный зашифрованный хэш ключа для контекста сертификата.

CERT_ARCHIVED_PROP_ID

Тип данных pvData: NULL. Если функция CertGetCertificateContextProperty возвращает значение true, то указанный идентификатор свойства существует для CERT_CONTEXT.

Указывает, что сертификат пропускается во время перечисления. Сертификат с этим набором свойств обнаруживается с помощью явных операций поиска, таких как те, которые используются для поиска сертификата с определенным хэшом или серийным номером. Данные в pvData не связаны с этим свойством.

CERT_AUTHORITY_INFO_ACCESS_PROP_ID

Этот идентификатор зарезервирован.

CERT_AUTO_ENROLL_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает строку Юникода, завершающуюся значением NULL, которая называет тип сертификата, для которого сертификат был зарегистрирован автоматически.

CERT_AUTO_ENROLL_RETRY_PROP_ID

Этот идентификатор зарезервирован.

CERT_BACKED_UP_PROP_ID

Этот идентификатор зарезервирован.

CERT_CA_DISABLE_CRL_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Отключает получение списка отзыва сертификатов (CRL) для сертификатов, используемых центром сертификации (ЦС). Если сертификат ЦС содержит это свойство, оно также должно содержать свойство CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID .

CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Содержит список URL-адресов протокола OCSP, используемых для сертификатов, выданных сертификатом ЦС. Содержимое массива — это байты в кодировке ASN.1 структуры X509_AUTHORITY_INFO_ACCESS, в которой pszAccessMethod имеет значение szOID_PKIX_OCSP.

CERT_CROSS_CERT_DIST_POINTS_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Расположение кросс-сертификатов. В настоящее время этот идентификатор применим только к сертификатам, но не к спискам отзыва сертификатов или спискам доверия сертификатов (CCL).

Массив BYTE содержит структуру CROSS_CERT_DIST_POINTS_INFO в кодировке ASN.1, декодированную с помощью функции CryptDecodeObject со значением X509_CROSS_CERT_DIST_POINTS для параметра lpszStuctType .

CERT_CTL_USAGE_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает массив байтов, содержащий структуру CTL_USAGE в кодировке ASN.1.

CERT_DATE_STAMP_PROP_ID

Тип данных pvData: указатель на структуру FILETIME .

Время добавления сертификата в хранилище.

CERT_DESCRIPTION_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает свойство, отображаемое в пользовательском интерфейсе сертификата. Это свойство позволяет пользователю описать использование сертификата.

CERT_EFS_PROP_ID

Этот идентификатор зарезервирован.

CERT_ENHKEY_USAGE_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает массив байтов, содержащий структуру CERT_ENHKEY_USAGE в кодировке ASN.1. Эта структура содержит массив идентификаторов объектов расширенного использования ключа (OID), каждый из которых указывает допустимое использование сертификата.

CERT_ENROLLMENT_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Сведения о регистрации ожидающего запроса, который содержит RequestID, CADNSName, CAName и DisplayName. Формат данных определяется следующим образом.

Байты Содержимое
Первые 4 байта Идентификатор ожидающего запроса
Следующие 4 байта Размер CADNSName в символах, включая завершающий символ NULL, за которым следует строка CADNSName с завершающим символом NULL.
Следующие 4 байта Размер CAName в символах, включая завершающий символ NULL, за которым следует строка CAName с завершающим символом NULL.
Следующие 4 байта Размер DisplayName в символах, включая завершающий символ NULL, за которым следует строка DisplayName с завершающим символом NULL.
 

CERT_EXTENDED_ERROR_INFO_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает строку символов Юникода, завершающуюся null, которая содержит расширенные сведения об ошибке для контекста сертификата.

CERT_FORTEZZA_DATA_PROP_ID

Этот идентификатор зарезервирован.

CERT_FRIENDLY_NAME_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает строку символов Юникода, завершающуюся null, которая содержит отображаемое имя сертификата.

CERT_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает хэш SHA1. Если хэш не существует, он вычисляется с помощью функции CryptHashCertificate .

CERT_HCRYPTPROV_OR_NCRYPT_KEY_HANDLE_PROP_ID

Тип данных pvData: указатель на HCRYPTPROV_OR_NCRYPT_KEY_HANDLE тип данных.

Возвращает вариант HCRYPTPROV или NCRYPT_KEY_HANDLE .

CERT_HCRYPTPROV_TRANSFER_PROP_ID

Возвращает дескриптор ключа API шифрования (CAPI), связанный с сертификатом. Вызывающий объект отвечает за освобождение дескриптора. Он не будет освобожден при освобождении контекста. Значение свойства удаляется после его возврата. При вызове этого свойства в контексте с ключом CNG возвращается CRYPT_E_NOT_FOUND .

CERT_IE30_RESERVED_PROP_ID

Этот идентификатор зарезервирован.

CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Хэш MD5 открытого ключа , связанного с закрытым ключом , используемым для подписания этого сертификата.

CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

MD5-хэш имени издателя и серийного номера из этого сертификата.

CERT_KEY_CONTEXT_PROP_ID

Тип данных pvData: указатель на структуру CERT_KEY_CONTEXT .

Возвращает структуру CERT_KEY_CONTEXT .

CERT_KEY_IDENTIFIER_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Если оно отсутствует, выполните поиск расширения szOID_SUBJECT_KEY_IDENTIFIER. Если это не удается, хэш SHA1 выполняется для элемента SubjectPublicKeyInfo сертификата для получения значений идентификатора.

CERT_KEY_PROV_HANDLE_PROP_ID

Тип данных pvData: указатель на значение HCRYPTPROV .

Возвращает дескриптор поставщика, полученный из CERT_KEY_CONTEXT_PROP_ID.

CERT_KEY_PROV_INFO_PROP_ID

Тип данных pvData: указатель на структуру CRYPT_KEY_PROV_INFO .

Возвращает указатель на структуру CRYPT_KEY_PROV_INFO .

CERT_KEY_SPEC_PROP_ID

Тип данных pvData: указатель на значение DWORD .

Возвращает значение DWORD , указывающее закрытый ключ, полученный из CERT_KEY_CONTEXT_PROP_ID, если он существует. В противном случае, если CERT_KEY_PROV_INFO_PROP_ID существует, он является источником dwKeySpec.

CERT_MD5_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает хэш MD5. Если хэш не существует, он вычисляется с помощью функции CryptHashCertificate .

CERT_NCRYPT_KEY_HANDLE_PROP_ID

Тип данных pvData: указатель на NCRYPT_KEY_HANDLE тип данных.

Возвращает CERT_NCRYPT_KEY_SPEC выбор, если применимо.

CERT_NCRYPT_KEY_HANDLE_TRANSFER_PROP_ID

Возвращает дескриптор ключа CNG, связанный с сертификатом. Вызывающий объект отвечает за освобождение дескриптора. Он не будет освобожден при освобождении контекста. Значение свойства удаляется после его возврата. При вызове этого свойства в контексте с устаревшим ключом (CAPI) возвращается CRYPT_E_NOT_FOUND .

CERT_NEW_KEY_PROP_ID

Этот идентификатор зарезервирован.

CERT_NEXT_UPDATE_LOCATION_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает структуру CERT_ALT_NAME_INFO в кодировке ASN.1.

CERT_NEXT_UPDATE_LOCATION_PROP_ID в настоящее время используется только с CCL.

CERT_NO_AUTO_EXPIRE_CHECK_PROP_ID

Этот идентификатор зарезервирован.

CERT_OCSP_CACHE_PREFIX_PROP_ID

Этот идентификатор зарезервирован.

CERT_OCSP_RESPONSE_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает закодированный ответ OCSP для этого сертификата.

CERT_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID

Тип данных pvData: указатель на строку Юникода, завершаемую null.

Возвращает строку L"<PUBKEY>/<BITLENGTH>", представляющую алгоритм открытого ключа сертификата и битовую длину. Поддерживаются следующие <алгоритмы PUBKEY> :

  • L"RSA" (BCRYPT_RSA_ALGORITHM)
  • L"DSA" (BCRYPT_DSA_ALGORITHM)
  • L"ECDSA" (SSL_ECDSA_ALGORITHM)
Windows 8 и Windows Server 2012: начинается поддержка этого свойства.

CERT_PUBKEY_ALG_PARA_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Для открытых ключей, поддерживающих наследование параметров алгоритма, возвращает параметры алгоритма PublicKey в кодировке ASN.1. Для стандарта цифровой подписи (DSS) возвращает параметры, закодированные с помощью функции CryptEncodeObject . Это свойство используется только в том случае, если определено CMS_PKCS7.

CERT_PUBKEY_HASH_RESERVED_PROP_ID

Этот идентификатор зарезервирован.

CERT_PVK_FILE_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает строку символов Юникода, завершающуюся null, которая содержит имя файла, содержащего закрытый ключ, связанный с открытым ключом сертификата.

CERT_RENEWAL_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает хэш обновленного сертификата.

CERT_REQUEST_ORIGINATOR_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает строку Юникода, завершающуюся значением NULL, которая содержит dns-имя компьютера для создания запроса контекста сертификата.

CERT_ROOT_PROGRAM_CERT_POLICIES_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает указатель на закодированную структуру CERT_POLICIES_INFO , содержащую политики приложений корневого сертификата для контекста. Это свойство можно декодировать с помощью функции CryptDecodeObject с параметром lpszStructType , равным X509_CERT_POLICIES , а для параметра dwCertEncodingType — сочетание X509_ASN_ENCODING побитового илиPKCS_7_ASN_ENCODING.

CERT_ROOT_PROGRAM_NAME_CONSTRAINTS_PROP_ID

Этот идентификатор зарезервирован.

CERT_SHA1_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает хэш SHA1. Если хэш не существует, он вычисляется с помощью функции CryptHashCertificate .

CERT_SIGN_HASH_CNG_ALG_PROP_ID

Тип данных pvData: указатель на строку Юникода, завершаемую null.

Возвращает строку L"<SIGNATURE>/<HASH>", представляющую подпись сертификата. Значение <SIGNATURE> определяет алгоритм открытого ключа CNG. Поддерживаются следующие алгоритмы:

  • L"RSA" (BCRYPT_RSA_ALGORITHM)
  • L"DSA" (BCRYPT_DSA_ALGORITHM)
  • L"ECDSA" (SSL_ECDSA_ALGORITHM)
Значение <HASH> определяет хэш-алгоритм CNG. Поддерживаются следующие алгоритмы:
  • L"MD5" (BCRYPT_MD5_ALGORITHM)
  • L"SHA1" (BCRYPT_SHA1_ALGORITHM)
  • L"SHA256" (BCRYPT_SHA256_ALGORITHM)
  • L"SHA384" (BCRYPT_SHA384_ALGORITHM)
  • L"SHA512" (BCRYPT_SHA512_ALGORITHM)
Ниже приведено несколько типичных примеров.
  • L"RSA/SHA1"
  • L"RSA/SHA256"
  • L"ECDSA/SHA256"
Windows 7 и Windows Server 2008 R2: Начинается поддержка этого свойства.

CERT_SIGNATURE_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает хэш подписи. Если хэш не существует, он вычисляется с помощью функции CryptHashToBeSigned . Длина хэша составляет 20 байт для SHA и 16 для MD5.

CERT_SMART_CARD_DATA_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает указатель на закодированные данные смарт-карта. Перед вызовом CertGetCertificateContextProperty эту константу можно использовать для получения сертификата смарт-карта с помощью функции CertFindCertificateInStore с параметром pvFindPara, равным CERT_SMART_CARD_DATA_PROP_ID, а параметру dwFindType присвоено значение CERT_FIND_PROPERTY.

CERT_SMART_CARD_ROOT_INFO_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает указатель на закодированную структуру CRYPT_SMART_CARD_ROOT_INFO .

CERT_SOURCE_LOCATION_PROP_ID

Этот идентификатор зарезервирован.

CERT_SOURCE_URL_PROP_ID

Этот идентификатор зарезервирован.

CERT_SUBJECT_DISABLE_CRL_PROP_ID

Этот идентификатор зарезервирован.

CERT_SUBJECT_INFO_ACCESS_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает расширение доступа к информации субъекта контекста сертификата в виде закодированной структуры CERT_SUBJECT_INFO_ACCESS .

CERT_SUBJECT_NAME_MD5_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает md5-хэш закодированного имени субъекта контекста сертификата.

CERT_SUBJECT_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID

Этот идентификатор зарезервирован.

CERT_SUBJECT_PUB_KEY_BIT_LENGTH_PROP_ID

Тип данных pvData: указатель на значение DWORD .

Возвращает длину (в битах) открытого ключа в сертификате.

Windows 8 и Windows Server 2012: начинается поддержка этого свойства.

CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BYTE . Размер этого массива указывается в параметре pcbData .

Возвращает хэш MD5 открытого ключа этого сертификата.

Для всех определяемых пользователем идентификаторов свойств pvData указывает на массив значений BYTE .

Дополнительные сведения о каждом идентификаторе свойства см. в документации по параметру dwPropId в разделе CertSetCertificateContextProperty.

[out] pvData

Указатель на буфер для получения данных в соответствии с dwPropId. Структуры, на которые указывают члены возвращаемой структуры, также возвращаются после базовой структуры. Поэтому размер, содержащийся в pcbData , часто превышает размер базовой структуры.

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

[in, out] pcbData

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

Чтобы получить требуемый размер буфера во время выполнения, передайте значение NULL для параметра pvData и задайте значение, указанное этим параметром, равным нулю. Если параметр pvData не равен NULL и размер, указанный в pcbData , меньше количества байтов, необходимых для хранения данных, функция завершается ошибкой, GetLastError возвращает ERROR_MORE_DATA, а требуемый размер помещается в переменную, на которую указывает параметр pcbData .

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

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

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

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

Ниже приведены некоторые возможные коды ошибок.

Код возврата Описание
CRYPT_E_NOT_FOUND
 Сертификат не имеет указанного свойства.
ERROR_MORE_DATA
 Если буфер, заданный параметром pvData , недостаточно велик для хранения возвращаемых данных, функция задает код ERROR_MORE_DATA и сохраняет требуемый размер буфера в байтах в переменной, на которую указывает pcbData.
 

Ошибки из вызываемой функции CryptHashCertificate можно распространить на эту функцию.

Комментарии

Свойства не хранятся в сертификате. Как правило, они связываются с сертификатом после получения ответа сертификата, а затем сохраняются вместе с сертификатом в хранилище. В целях безопасности рекомендуется проверять значения свойств перед их сохранением и сохранять в пользовательских хранилищах только информационные свойства, такие как значение CERT_FRIENDLY_NAME_PROP_ID . Все остальные типы свойств должны сохраняться в хранилищах на локальном компьютере.

Код может использовать макрос для оценки класса хэша для контекста сертификата. Дополнительные сведения см. в разделе CertSetCertificateContextProperty.

Примеры

Примеры использования этой функции см. в разделах Example C Program: Getting and Setting Certificate Properties и Example C Program: Listing the Certificates in a Store.

Требования

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

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

CERT_KEY_CONTEXT

CertCreateCertificateContext

CertSetCertificateContextProperty

CryptHashCertificate

CryptHashToBeSigned

Расширенные функции свойств