Функция 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
Дескриптор подсистемы цепочки (пространство имен и кэш) для использования. Если hChainEngineNULL, используется подсистема цепочки по умолчанию HCCE_CURRENT_USER. Этот параметр можно задать для HCCE_LOCAL_MACHINE.
[in] pCertContext
Указатель на CERT_CONTEXT конечного сертификата, сертификат, для которого создается цепочка. Этот контекст сертификата будет элементом нулевого индекса в первой простой цепочке.
[in, optional] pTime
Указатель на переменную FILETIME, указывающую время проверки цепочки. Обратите внимание, что время не влияет на список доверия, отзыв или проверку корневого хранилища. Текущее системное время используется, если null передается этому параметру. Доверие к определенному сертификату, являющегося доверенным корнем, основано на текущем состоянии корневого хранилища, а не на состоянии корневого хранилища в то время, которое передается этим параметром. Для отзыва список отзыва сертификатов (CRL), сам по себе должен быть допустимым в текущее время. Значение этого параметра используется для определения того, был ли отозван сертификат, указанный в списке отзыва сертификатов.
[in] hAdditionalStore
Дескриптор любого дополнительного хранилища для поиска вспомогательных сертификатов и списков доверия сертификатов списки (CTLs). Этот параметр может быть значение NULL, если не требуется выполнять поиск в дополнительном хранилище.
[in] pChainPara
Указатель на структуру CERT_CHAIN_PARA, содержащую параметры цепочки.
[in] dwFlags
Значения флагов, указывающие на специальную обработку. Этот параметр может быть сочетанием одного или нескольких следующих флагов.
| Ценность | Значение |
|---|---|
|
При установке этого флага конечный сертификат кэшируется, что может ускорить процесс создания цепочки. По умолчанию конечный сертификат не кэшируется, и он должен быть проверен каждый раз, когда для него создается цепочка. |
|
Проверка отзыва обращается только к кэшируемым URL-адресам. |
|
Этот флаг используется во время создания цепочки для протокола состояния онлайн-сертификата (OCSP), чтобы предотвратить циклические проверки отзыва. Во время создания цепочки, если ответ OCSP подписан независимым подписчиком OCSP, то в дополнение к исходной сборке цепочки существует вторая цепочка, созданная для самого сертификата подписи OCSP. Этот флаг используется во время сборки второй цепочки для подавления рекурсивного независимого сертификата подписи OCSP. Если сертификат подписи содержит расширение szOID_PKIX_OCSP_NOCHECK, проверка отзыва пропускается для конечного сертификата подписи. Разрешена проверка OCSP и CRL.
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_ROOTdwErrorStatus элемента параметра 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] |
| целевая платформа | Виндоус |
| заголовка | wincrypt.h |
| библиотеки |
Crypt32.lib |
| DLL | Crypt32.dll |
См. также
Функции проверки цепочки сертификатов
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по