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

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

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

[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: созданиецепочки сертификатов.

Требования

См. также

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

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