Функция CertGetCertificateChain (wincrypt.h)
Функция CertGetCertificateChain создает контекст цепочки сертификатов, начиная с конечного сертификата и возвращаясь, если это возможно, к доверенному корневому сертификату.
Синтаксис
BOOL CertGetCertificateChain(
[in, optional] HCERTCHAINENGINE hChainEngine,
[in] PCCERT_CONTEXT pCertContext,
[in, optional] LPFILETIME pTime,
[in] HCERTSTORE hAdditionalStore,
[in] PCERT_CHAIN_PARA pChainPara,
[in] DWORD dwFlags,
[in] LPVOID pvReserved,
[out] PCCERT_CHAIN_CONTEXT *ppChainContext
);
Параметры
[in, optional] hChainEngine
Дескриптор обработчика цепочки (пространство имен и кэш) для использования. Если hChainEngine имеет значение NULL, используется обработчик цепей по умолчанию, HCCE_CURRENT_USER. Для этого параметра можно задать значение HCCE_LOCAL_MACHINE.
[in] pCertContext
Указатель на CERT_CONTEXT конечного сертификата, для которого создается цепочка. Этот контекст сертификата будет элементом нулевого индекса в первой простой цепочке.
[in, optional] pTime
Указатель на переменную FILETIME , указывающую время проверки цепочки. Обратите внимание, что время не влияет на список доверия, отзыв или проверку корневого хранилища. Текущее системное время используется, если этому параметру передается значение NULL . Доверие к определенному сертификату, являющегося доверенным корневым, основано на текущем состоянии корневого хранилища, а не на состоянии корневого хранилища в момент, передаваемом этим параметром. Для отзыва сам список отзыва сертификатов (CRL) должен быть действительным в текущий момент времени. Значение этого параметра используется для определения того, был ли отозван сертификат, указанный в списке отзыва сертификатов.
[in] hAdditionalStore
Дескриптор для любого дополнительного хранилища для поиска вспомогательных сертификатов и списков доверия сертификатов (CCL). Этот параметр может иметь значение NULL , если поиск в дополнительном хранилище не требуется.
[in] pChainPara
Указатель на структуру CERT_CHAIN_PARA , включающую параметры построения цепочки.
[in] dwFlags
Пометки значений, указывающих на специальную обработку. Этот параметр может быть сочетанием одного или нескольких следующих флагов.
| Значение | Значение |
|---|---|
|
Если этот флаг установлен, конечный сертификат кэшируется, что может ускорить процесс создания цепочки. По умолчанию конечный сертификат не кэшируется, и его необходимо проверять при каждой сборке цепочки. |
|
Проверка отзыва обращается только к кэшируемым URL-адресам. |
|
Этот флаг используется во время создания цепочки для сертификата подписателя протокола OCSP, чтобы предотвратить циклические проверки отзыва. Если во время создания цепочки ответ OCSP подписывается независимым подписывателем OCSP, то в дополнение к исходной сборке цепочки существует вторая цепочка, созданная для самого сертификата подписателя OCSP. Этот флаг используется во время сборки второй цепочки для подавления рекурсивного независимого сертификата подписателя OCSP. Если сертификат подписывателя содержит расширение szOID_PKIX_OCSP_NOCHECK , проверка отзыва для сертификата конечного подписателя пропускается. Проверка OCSP и списка отзыва сертификатов разрешена.
Windows Server 2003 и Windows XP: Это значение не поддерживается. |
|
Использует только кэшированные URL-адреса при создании цепочки сертификатов. В Интернете и интрасети не выполняется поиск объектов на основе URL-адресов.
Примечание Этот флаг не применяется к проверке отзыва. Задайте для CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY использовать только кэшированные URL-адреса для проверки отзыва. |
|
По соображениям производительности во втором проходе построения цепочки учитываются только потенциальные пути цепочки, качество которых превышает или равное самому высокому качеству, определенному во время первого прохода. Первый проход учитывает только допустимую подпись, полную цепочку и доверенные корневые элементы для вычисления качества цепочки. Этот флаг можно установить, чтобы отключить эту оптимизацию и учитывать все потенциальные пути цепочки во время второго прохода. |
|
Этот флаг не поддерживается. Сертификаты в хранилище My никогда не считаются доверенными для одноранговых узлов. |
|
Сертификаты конечных сущностей в хранилище TrustedPeople являются доверенными без создания цепочки. Эта функция не задает CERT_TRUST_IS_PARTIAL_CHAIN или CERT_TRUST_IS_UNTRUSTED_ROOT битов элементов dwErrorStatus параметра ppChainContext. Windows Server 2003 Windows XP : Этот флаг не поддерживается. |
|
Установка этого флага указывает, что вызывающий объект хочет согласиться на проверку слабых подписей.
Этот флаг доступен в накопительном обновлении для каждой ОС, начиная с Windows 7 и Windows Server 2008 R2. |
|
По умолчанию возвращается только путь цепочки наивысшего качества. Установка этого флага вернет цепочки низкого качества. Они возвращаются в полях cLowerQualityChainContext и rgpLowerQualityChainContext контекста цепочки. |
|
Установка этого флага запрещает автоматическое обновление сторонних корневых тонов с веб-сервера клиентский компонент Центра обновления Windows. |
|
Если задать CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT, а также указать значение элемента dwUrlRetrievalTimeout структуры CERT_CHAIN_PARA , значение, указанное в dwUrlRetrievalTimeout , представляет собой совокупное время ожидания для всех извлечений URL-адресов отзыва.
Если задать CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT, но не указать значение dwUrlRetrievalTimeout , максимальное совокупное время ожидания по умолчанию равно 20 секундам. Время ожидания каждого проверенного URL-адреса истекает после прохождения половины оставшегося совокупного баланса. То есть первый URL-адрес истекает через 10 секунд, второй — через 5 секунд, третий — через 2,5 секунды и т. д., пока URL-адрес не будет успешным, 20 секунд не пройдет или URL-адреса больше не будут проверяться. Если CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT не задано, каждому URL-адресу отзыва в цепочке назначается максимальное время ожидания, равное значению, указанному в dwUrlRetrievalTimeout. Если не указать значение для элемента dwUrlRetrievalTimeout , каждому URL-адресу отзыва назначается максимальное время ожидания по умолчанию в 15 секунд. Если URL-адрес не выполняется успешно, максимальное совокупное значение времени ожидания составляет 15 секунд, умноженное на количество URL-адресов в цепочке. Значения по умолчанию можно задать с помощью групповая политика. |
|
Если этот флаг установлен, pTime используется в качестве времени метки времени, чтобы определить, действителен ли конечный сертификат. Текущее время также можно использовать, чтобы определить, остается ли действительным конечный сертификат. Все остальные сертификаты центра сертификации (ЦС) и корневые сертификаты в цепочке проверяются с использованием текущего времени, а не pTime. |
|
Установка этого флага явным образом отключает извлечение сведений об авторизации (AIA). |
Можно также задать следующие флаги отзыва, но одновременно может быть установлен только один флаг из этой группы.
[in] pvReserved
Этот параметр зарезервирован и должен иметь значение NULL.
[out] ppChainContext
Адрес указателя на созданный контекст цепочки. Завершив использование контекста цепочки, разблокируйте цепочку, вызвав функцию CertFreeCertificateChain .
Возвращаемое значение
Если функция выполняется успешно, функция возвращает ненулевое значение (TRUE).
Если функция завершается сбоем, она возвращает ноль (FALSE). Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError.
Комментарии
Когда приложение запрашивает цепочку сертификатов, возвращаемая структура имеет форму CERT_CHAIN_CONTEXT. Этот контекст содержит массив структур CERT_SIMPLE_CHAIN , в которых каждая простая цепочка переходит от конечного сертификата к самозаверяющему сертификату. Контекст цепочки соединяет простые цепочки через списки доверия. Каждая простая цепочка содержит цепочку сертификатов, сводную информацию о доверии о цепочке и сведения о доверии для каждого элемента сертификата в цепочке.
Следующие замечания относятся к проверке строгой сигнатуры:
- Вы можете включить проверку строгой подписи для этой функции, задав элемент pStrongSignParaструктуры CERT_CHAIN_PARA , на которую указывает параметр pChainPara .
- Если в цепочке найден сертификат без строгой сигнатуры, ошибки CERT_TRUST_HAS_WEAK_SIGNATURE и CERT_TRUST_IS_NOT_SIGNATURE_VALID задаются в поле dwErrorStatus структуры CERT_TRUST_STATUS . Параметр ppChainContext указывает на CERT_CHAIN_CONTEXT структуру, которая, в свою очередь, указывает на структуру CERT_TRUST_STATUS .
- Если цепочка строго подписана, открытый ключ в конечном сертификате проверяется, соответствует ли он требованиям к минимальной длине открытого ключа для строгой подписи. Если условие не выполнено, ошибки CERT_TRUST_HAS_WEAK_SIGNATURE и CERT_TRUST_IS_NOT_SIGNATURE_VALID задаются в поле dwErrorStatus структуры CERT_TRUST_STATUS . Чтобы отключить проверку длины ключа, задайте значение CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG в элементе dwStrongSignFlagsструктуры CERT_CHAIN_PARA , на которую указывает параметр pChainPara .
- Если флаги CERT_STRONG_SIGN_ENABLE_CRL_CHECK или CERT_STRONG_SIGN_ENABLE_OCSP_CHECK заданы в структуре CERT_STRONG_SIGN_SERIALIZED_INFO и ответ CRL или OCSP найден без строгой сигнатуры, ответ CRL или OCSP будет рассматриваться как автономный. То есть ошибки CERT_TRUST_IS_OFFLINE_REVOCATION и CERT_TRUST_REVOCATION_STATUS_UNKNOWN задаются в поле dwErrorStatus структуры CERT_TRUST_STATUS . Кроме того, член dwRevocationResult структуры CERT_REVOCATION_INFO имеет значение NTE_BAD_ALGID.
Примеры
Пример использования этой функции см. в разделе Пример программы C. Создание цепочки сертификатов.
Требования
| Минимальная версия клиента | Windows XP [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | wincrypt.h |
| Библиотека | Crypt32.lib |
| DLL | Crypt32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по