Функция CertFindChainStore (wincrypt.h)

Статья
03/15/2023

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

Синтаксис

PCCERT_CHAIN_CONTEXT CertFindChainInStore(
  [in] HCERTSTORE           hCertStore,
  [in] DWORD                dwCertEncodingType,
  [in] DWORD                dwFindFlags,
  [in] DWORD                dwFindType,
  [in] const void           *pvFindPara,
  [in] PCCERT_CHAIN_CONTEXT pPrevChainContext
);

Параметры

[in] hCertStore

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

[in] dwCertEncodingType

Тип кодирования сертификата , который использовался для кодирования хранилища. Тип кодирования сообщений , содержащийся в word этого значения, игнорируется этой функцией.

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

Ценность	Значение
X509_ASN_ENCODING 1 (0x1)	Задает кодировку сертификата X.509.

[in] dwFindFlags

Содержит дополнительные параметры поиска. Возможные значения этого параметра зависят от значения параметра dwFindType.

Этот параметр может содержать ноль или сочетание одного или нескольких следующих значений, если dwFindType содержит CERT_CHAIN_FIND_BY_ISSUER.

Ценность	Значение
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	Сравнивает открытый ключ в сертификате с открытогоключа поставщика служб шифрования. Это сравнение является последней проверкой, сделанной в цепочке при его построении. Так как hCryptProv член издателя содержит закрытый ключ, его может потребоваться проверить несколько раз во время этого процесса; чтобы упростить эту проверку, элемент dwAcquirePrivateKeyFlags можно задать в структуре CERT_CHAIN_FIND_BY_ISSUER_PARA, чтобы включить кэширование этого hCryptProv.
CERT_CHAIN_FIND_BY_ISSUER_COMPLEX_CHAIN_FLAG	По умолчанию проверяется только первая простая цепочка для совпадений имени издателя. При использовании этого набора флагов значение по умолчанию переопределяется, а последующие простые цепочки также проверяются на совпадения имени издателя.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_FLAG	Повышает производительность этой функции, вызывая поиск только кэшированных системных хранилищ (root, My, Ca, Trust) для поиска сертификатов издателя. Если этот флаг не задан, функция выполняет поиск кэшированных системных хранилищ и хранилище, представленное параметром hCertStore.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_URL_FLAG	Выполняется поиск только кэша URL-адресов. Интернет не выполняется.
CERT_CHAIN_FIND_BY_ISSUER_LOCAL_MACHINE_FLAG	Открывает только хранилища сертификатов локального компьютера. Хранилища сертификатов текущего пользователя не открываются.
CERT_CHAIN_FIND_BY_ISSUER_NO_KEY_FLAG	Проверка не выполняется, чтобы определить, имеет ли сертификат связанный закрытый ключ.

[in] dwFindType

Определяет, какие критерии следует использовать для поиска сертификата в хранилище.

Этот параметр может быть следующим заданным в данный момент значением.

CERT_CHAIN_FIND_BY_ISSUER

Находит сертификат на основе имени издателя. Параметр pvFindPara — это указатель на структуру CERT_CHAIN_FIND_BY_ISSUER_PARA, содержащую элементы, изменяющие поиск.

Цепочка сертификатов создается для сертификата с доступным закрытым ключом. По умолчанию сравниваются только издатели в первой простой цепочке в соответствии с именем издателя. Если этот флаг задан, все цепочки проверяются на сертификат издателя, соответствующий одному из наборов имен издателей.

Эта функция сравнивает имя BLOB-объектов, передаваемых в структуре pvFindPara, с любым центром сертификации (ЦС) в цепочке, а не только центром сертификации в корневом сертификате.

Эта функция не выполняет никаких проверок отзыва.

Если pPrevChainContext не NULL, эта функция возвращает цепочку для другого сертификата при каждом вызове функции. Если имеется только один подходящий сертификат, но существует два сопоставления выданных центров сертификации, одно из которых отозвано, это можно сделать, чтобы эта функция возвращала отозванную цепочку. Если приложение проверяет наличие отзыва через вызовы функции CertVerifyRevocation и находит цепочку неподходящими, дополнительный вызов функции CertFindChainStore не вернет цепочку, содержащую тот же сертификат из допустимого центра сертификации. Вместо этого он возвращает совершенно другую цепочку с другим сертификатом или NULL, если такая цепочка не найдена.

[in] pvFindPara

Указатель, содержащий дополнительные критерии поиска. Тип и формат данных, на которые указывает этот параметр, зависит от значения параметра dwFindType.

[in] pPrevChainContext

Указатель на структуру CERT_CHAIN_CONTEXT, возвращенную из предыдущего вызова этой функции. Поиск начинается с этого сертификата. Для первого вызова этой функции этот параметр должен быть null. В последующих вызовах это указатель, возвращаемый предыдущим вызовом функции. Если этот параметр не null, эта функция освобождает эту структуру.

Возвращаемое значение

Если первый или следующий контекст цепочки не построен, возвращается NULL. В противном случае возвращается указатель на структуру только для чтения CERT_CHAIN_CONTEXT. Структура CERT_CHAIN_CONTEXT освобождается при передаче в качестве параметра pPrevChainContext при последующем вызове этой функции. В противном случае структура CERT_CHAIN_CONTEXT должна быть освобождена явным образом путем вызова функции CertFreeCertificateChain.

Замечания

Параметр pPrevChainContext должен быть null при первом вызове для создания контекста цепочки. Чтобы создать контекст следующей цепочки, pPrevChainContext устанавливается в структуру CERT_CHAIN_CONTEXT, возвращаемую предыдущим вызовом. Если pPrevChainContext не NULL, структура всегда освобождается этой функцией с помощью функции CertFreeCertificateChain, даже если возникает ошибка.

Требования

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