Функция CertGetCertificateContextProperty (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: указатель на массив значений BY TE. Размер этого массива указывается в параметре pcbData.

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

CERT_ARCHIVED_PROP_ID

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

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

CERT_AUTHORITY_INFO_ACCESS_PROP_ID

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

CERT_AUTO_ENROLL_PROP_ID

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

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

CERT_AUTO_ENROLL_RETRY_PROP_ID

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

CERT_BACKED_UP_PROP_ID

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

CERT_CA_DISABLE_CRL_PROP_ID

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

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

CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID

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

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

CERT_CROSS_CERT_DIST_POINTS_PROP_ID

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

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

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

CERT_CTL_USAGE_PROP_ID

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

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

CERT_DATE_STAMP_PROP_ID

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

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

CERT_DESCRIPTION_PROP_ID

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

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

CERT_EFS_PROP_ID

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

CERT_ENHKEY_USAGE_PROP_ID

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

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

CERT_ENROLLMENT_PROP_ID

Тип данных pvData: указатель на массив значений BY TE. Размер этого массива указывается в параметре 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: указатель на массив значений BY TE. Размер этого массива указывается в параметре pcbData.

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

CERT_FORTEZZA_DATA_PROP_ID

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

CERT_FRIENDLY_NAME_PROP_ID

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

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

CERT_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BY TE. Размер этого массива указывается в параметре 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: указатель на массив значений BY TE. Размер этого массива указывается в параметре pcbData.

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

CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID

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

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

CERT_KEY_CONTEXT_PROP_ID

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

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

CERT_KEY_IDENTIFIER_PROP_ID

Тип данных pvData: указатель на массив значений BY TE. Размер этого массива указывается в параметре 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: указатель на массив значений BY TE. Размер этого массива указывается в параметре 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: указатель на массив значений BY TE. Размер этого массива указывается в параметре pcbData.

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

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

CERT_NO_AUTO_EXPIRE_CHECK_PROP_ID

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

CERT_OCSP_CACHE_PREFIX_PROP_ID

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

CERT_OCSP_RESPONSE_PROP_ID

Тип данных pvData: указатель на массив значений BY TE. Размер этого массива указывается в параметре 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: указатель на массив значений BY TE. Размер этого массива указывается в параметре pcbData.

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

CERT_PUBKEY_HASH_RESERVED_PROP_ID

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

CERT_PVK_FILE_PROP_ID

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

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

CERT_RENEWAL_PROP_ID

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

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

CERT_REQUEST_ORIGINATOR_PROP_ID

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

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

CERT_ROOT_PROGRAM_CERT_POLICIES_PROP_ID

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

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

CERT_ROOT_PROGRAM_NAME_CONSTRAINTS_PROP_ID

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

CERT_SHA1_HASH_PROP_ID

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

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

CERT_SHA1_SHA256_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BY TE. Размер этого массива составляет 52 байта, 20 байтов для хэша SHA1 и 32 байта для хэша SHA256.

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

CERT_SHA256_HASH_PROP_ID

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

Возвращает хэш SHA256. Если хэш не существует, он вычисляется с помощью функции 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: указатель на массив значений BY TE. Размер этого массива указывается в параметре pcbData.

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

CERT_SMART_CARD_DATA_PROP_ID

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

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

CERT_SMART_CARD_ROOT_INFO_PROP_ID

Тип данных pvData: указатель на массив значений BY TE. Размер этого массива указывается в параметре 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: указатель на массив значений BY TE. Размер этого массива указывается в параметре pcbData.

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

CERT_SUBJECT_NAME_MD5_HASH_PROP_ID

Тип данных pvData: указатель на массив значений BY TE. Размер этого массива указывается в параметре 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: указатель на массив значений BY TE. Размер этого массива указывается в параметре 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.

Примеры

Примеры, использующие эту функцию, см. в статье Пример программы C: получение и настройка свойств сертификата и пример программы C: перечисление сертификатов вМагазина.

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows XP [классические приложения | Приложения UWP]
минимальный поддерживаемый сервер Windows Server 2003 [классические приложения | Приложения UWP]
целевая платформа Виндоус
заголовка wincrypt.h
библиотеки Crypt32.lib
DLL Crypt32.dll

См. также

CERT_KEY_CONTEXT

CertCreateCertificateContext

CertSetCertificateContextProperty

CryptHashCertificate

CryptHashToBeSigned

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