Поделиться через


Функция 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

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

Ценность Значение
CERT_CHAIN_CACHE_END_CERT
0x00000001
При установке этого флага конечный сертификат кэшируется, что может ускорить процесс создания цепочки. По умолчанию конечный сертификат не кэшируется, и он должен быть проверен каждый раз, когда для него создается цепочка.
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
0x80000000
Проверка отзыва обращается только к кэшируемым URL-адресам. Это позволит предотвратить получение сетевых сертификатов или OCSP для сертификатов конца или ЦС. CACHE_ONLY зависит от приятеля на компьютере, чтобы уже получить CRL или OCSP из сети.
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT
0x04000000
Этот флаг используется во время создания цепочки для протокола состояния онлайн-сертификата (OCSP), чтобы предотвратить циклические проверки отзыва. Во время создания цепочки, если ответ OCSP подписан независимым подписчиком OCSP, то в дополнение к исходной сборке цепочки существует вторая цепочка, созданная для самого сертификата подписи OCSP. Этот флаг используется во время сборки второй цепочки для подавления рекурсивного независимого сертификата подписи OCSP. Если сертификат подписи содержит расширение szOID_PKIX_OCSP_NOCHECK, проверка отзыва пропускается для конечного сертификата подписи. Разрешена проверка OCSP и CRL.

Windows Server 2003 и Windows XP: это значение не поддерживается.
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
0x00000004
Использует только кэшированные URL-адреса при создании цепочки сертификатов. Интернет и интрасеть не ищут объекты на основе URL-адресов, такие как кабины CTL, корни сторонних производителей и издатели AIA. Большинство корней должны находиться в ресурсе crypt32.dll. В противном случае это извлечение необходимо, чтобы предотвратить ошибку построения цепочки. Эти кабины и корни размещаются на высокопроизводительных серверах Microsoft CDN.

Примечание. этот флаг неприменимо к проверке отзыва. Задайте CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY использовать только кэшированные URL-адреса для проверки отзыва. Как правило, кабины CTL уже предварительно извлекаются через службу cryptsvc.
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING0x00000040 По соображениям производительности второй проход цепочки здания учитывает только потенциальные пути цепочки, которые имеют качество больше или равно самому высокому качеству, определенному во время первого прохода. Первый проход рассматривает только допустимую подпись, полную цепочку и доверенные корни для вычисления качества цепочки. Этот флаг можно задать, чтобы отключить эту оптимизацию и рассмотреть все потенциальные пути цепочки во время второго прохода.
CERT_CHAIN_DISABLE_MY_PEER_TRUST
0x00000800
Этот флаг не поддерживается. Сертификаты в хранилище "My" никогда не учитываются для доверия одноранговых узлов.
CERT_CHAIN_ENABLE_PEER_TRUST
0x00000400
Конечные сертификаты сущностей в хранилище TrustedPeople являются доверенными, не выполняя сборку цепочки. Эта функция не задает биты элементов CERT_TRUST_IS_PARTIAL_CHAIN или CERT_TRUST_IS_UNTRUSTED_ROOTdwErrorStatus элемента параметра ppChainContext.

Windows Server 2003 и Windows XP: этот флаг не поддерживается.
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE
0x00010000
Установка этого флага указывает, что вызывающий объект хочет принять участие в ненадежных проверках подписи.

Этот флаг доступен в накопительном обновлении для каждой ОС, начиная с Windows 7 и Windows Server 2008 R2.
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS
0x00000080
По умолчанию возвращается только путь цепочки высокого качества. Установка этого флага вернет более низкие цепочки качества. Они возвращаются в полях cLowerQualityChainContext и rgpLowerQualityChainContext контекста цепочки.
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE
0x00000100
Установка этого флага препятствует автоматическому обновлению сторонних корней из веб-сервера Центра обновления Windows.
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT
0x08000000
Если задать 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-адресов в цепочке.

Значения по умолчанию можно задать с помощью групповой политики.
CERT_CHAIN_TIMESTAMP_TIME
0x00000200
Если этот флаг задан, pTime используется в качестве времени метки времени для определения допустимости конечного сертификата. Текущее время также можно использовать для определения того, остается ли конечный сертификат допустимым временем. Все остальные центра сертификации (ЦС) и корневые сертификаты в цепочке проверяются с помощью текущего времени, а не pTime.
CERT_CHAIN_DISABLE_AIA
0x00002000
Задание этого флага явно отключает извлечение сведений об центрах (AIA). Иногда серверы TLS настроены неправильно и не включают правильные сертификаты ЦС в подтверждение.

Вы также можете задать следующие флаги отзыва, но одновременно можно задать только один флаг из этой группы.

Ценность Значение
CERT_CHAIN_REVOCATION_CHECK_END_CERT
0x10000000
Проверка отзыва выполняется только для конечного сертификата и только конечного сертификата.
CERT_CHAIN_REVOCATION_CHECK_CHAIN
0x20000000
Проверка отзыва выполняется для всех сертификатов в каждой цепочке.
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT
0x40000000
Проверка отзыва выполняется для всех сертификатов во всех цепочках, кроме корневого сертификата.

[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.

Следующие рекомендации применяются к любому приложению Windows, вызываемому этими API, для проверки сертификата проверки подлинности сервера TLS:

  • Включить проверку отзыва только для конечного сертификата.
    • Задайте флаг CERT_CHAIN_REVOCATION_CHECK_END_CERT.
    • Большинство сертификатов ЦС имеют срок действия CRL от 1 до 6 месяцев.
      • Так как скачанные списки отзыва сертификатов кэшируются, срок действия слишком длинный, чтобы иметь большое значение.
    • Если существует компрометация ЦС, сертификаты также будут добавлены в сертификат Windows, запрещенный CTL
    • Рекомендуемая практика для tls-серверов — поддержка среза OCSP для конечного сертификата.
      • В этом случае извлечение сети не потребуется, если не истек срок действия срезанные ответы OCSP.
  • Включите получение сетевых адресов для CCL, OCSP, издателей AIA и такси CTL платформы Windows и сторонних корней.
    • Если заданы указанные выше CERT_CHAIN_REVOCATION_CHECK_END_CERT, это значение по умолчанию.
    • Не устанавливайте ни один из следующих флагов, чтобы предотвратить извлечение сети. Дополнительные сведения об этих флагах см. в таблице dwFlags, приведенной выше:
      • CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
      • CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
      • CERT_CHAIN_DISABLE_AIA
  • Включите накопительное время ожидания для извлечения сети CRL и OCSP.
    • Задайте флаг CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT, переданный CertGetCertificateChain.
    • Предоставляет верхний предел общего времени, разрешенного для получения списков отзыва сертификатов и сетевых запросов OCSP.
  • Уменьшите максимальное время, допустимое для каждого извлечения сети, с 15 до 10 секунд.
    • Задайте поле dwUrlRetrievalTimeout в CERT_CHAIN_PARA, переданное в CertGetCertificateChain значение 10 * 1000 миллисекундах.
    • Это также сокращает время ожидания с 20 до 10 секунд.
      • Для конечных сертификатов следует скачать только ответы OCSP. 5 секунд должно быть достаточно для этого скачивания.
  • Игнорировать ошибки отзыва в автономном режиме.
    • Задайте CERT_CHAIN_POLICY_IGNORE_ALL_REV_UNKNOWN_FLAGS в CERT_CHAIN_POLICY_PARA, переданной CertVerifyCertificateChainPolicy(CERT_CHAIN_POLICY_SSL).
    • Получение сети OCSP и CRL является лучшей попыткой. Большинство извлекаемых сетей должны успешно выполняться в течение нескольких секунд, но это не гарантируется 100%.
  • Сведения о проверке сертификатов в кэше.
    • Задайте CERT_CHAIN_CACHE_END_CERT.
      • Включает кэширование LRU сведений о конечных сертификатах в дополнение к промежуточным сертификатам.
    • Обычно выполняется несколько подключений TLS к одному серверу.

Примеры

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

Требования

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

См. также

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

Функции проверки цепочки сертификатов