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

  • Статья

Функция CertSelectCertificateChains извлекает цепочки сертификатов на основе указанных критериев выбора.

Синтаксис

BOOL CertSelectCertificateChains(
  [in, optional] LPCGUID                  pSelectionContext,
  [in]           DWORD                    dwFlags,
  [in, optional] PCCERT_SELECT_CHAIN_PARA pChainParameters,
  [in]           DWORD                    cCriteria,
  [in, optional] PCCERT_SELECT_CRITERIA   rgpCriteria,
  [in]           HCERTSTORE               hStore,
  [out]          PDWORD                   pcSelection,
  [out]          PCCERT_CHAIN_CONTEXT     **pprgpSelection
);

Параметры

[in, optional] pSelectionContext

Указатель на GUID сценария выбора сертификата, используемого для этого вызова.

[in] dwFlags

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

Значение Значение
CERT_SELECT_ALLOW_EXPIRED
 Выберите сертификаты с истекшим сроком действия, соответствующие критериям выбора. По умолчанию сертификаты с истекшим сроком действия отклоняются из выбора.
CERT_SELECT_TRUSTED_ROOT
 Выберите сертификаты, для которых для бита ошибки в состоянии доверия цепочки сертификатов не задано значение CERT_TRUST_IS_UNTRUSTED_ROOT, CERT_TRUST_IS_PARTIAL_CHAIN или CERT_TRUST_IS_NOT_TIME_VALID.

Кроме того, не выбираются сертификаты, имеющие одну из следующих ошибок недопустимого ограничения:

  • CERT_TRUST_INVALID_POLICY_CONSTRAINTS
  • CERT_TRUST_INVALID_BASIC_CONSTRAINTS
  • CERT_TRUST_INVALID_NAME_CONSTRAINTS
CERT_SELECT_DISALLOW_SELFSIGNED
 Выберите сертификаты, которые не являются самозаверяющими и самозаверяющими.
CERT_SELECT_HAS_PRIVATE_KEY
 Выберите сертификаты, для которых задано значение для свойства CERT_KEY_PROV_INFO_PROP_ID сертификата.
CERT_SELECT_HAS_KEY_FOR_SIGNATURE
 Выберите сертификаты, для которых для элемента dwKeySpec свойства CERT_KEY_PROV_INFO_PROP_ID задано значение AT_SIGNATURE.

Если эта функция вызывается как часть приложения с поддержкой CNG и члену dwKeySpec свойства CERT_KEY_PROV_INFO_PROP_ID задано значение -1, выберите сертификаты, для которых значение свойства NCRYPT_KEY_USAGE_PROPERTY связанного закрытого ключа имеет NCRYPT_ALLOW_SIGNING_FLAG .
CERT_SELECT_HAS_KEY_FOR_KEY_EXCHANGE
 Выберите сертификаты, для которых для элемента dwKeySpec свойства CERT_KEY_PROV_INFO_PROP_ID задано значение AT_KEYEXCHANGE.

Если эта функция вызывается как часть приложения с поддержкой CNG и члену dwKeySpec свойства CERT_KEY_PROV_INFO_PROP_ID задано значение -1, выберите сертификаты, для которых задан NCRYPT_ALLOW_DECRYPT_FLAG или NCRYPT_ALLOW_KEY_AGREEMENT_FLAG .
CERT_SELECT_HARDWARE_ONLY
 Выберите сертификаты, для которых свойству PP_IMPTYPE связанного поставщика закрытых ключей присваивается значение CRYPT_IMPL_HARDWARE или CRYPT_IMPL_REMOVABLE. (Для поставщиков CNG NCRYPT_IMPL_TYPE_PROPERTY значение свойства ДОЛЖНО иметь NCRYPT_IMPL_HARDWARE_FLAG или NCRYPT_IMPL_REMOVABLE_FLAG бит).

Если эта функция вызывается как часть приложения с поддержкой CNG, выберите сертификаты, для которых свойству NCRYPT_IMPL_TYPE_PROPERTY присвоено значение NCRYPT_IMPL_HARDWARE_FLAG или NCRYPT_IMPL_REMOVABLE_FLAG.
CERT_SELECT_ALLOW_DUPLICATES
 Разрешите выбор сертификатов, для которых альтернативное имя субъекта и субъекта содержат одинаковые сведения, а значение расширения шаблона сертификата эквивалентно. По умолчанию, если сертификаты соответствуют этому критерию, выбирается только последний сертификат.

[in, optional] pChainParameters

Указатель на структуру CERT_SELECT_CHAIN_PARA для указания параметров построения цепочки. Если значение РАВНО NULL, будут использоваться параметры по умолчанию.

Элемент pChainPara структуры CERT_SELECT_CHAIN_PARA указывает на CERT_CHAIN_PARA структуру, которую можно использовать для включения строгого подписывания.

[in] cCriteria

Количество элементов в массиве, на который указывает массив rgpCriteria .

[in, optional] rgpCriteria

Указатель на массив CERT_SELECT_CRITERIA структур, определяющих критерии выбора. Если для этого параметра задано значение NULL, значение параметра cCriteria должно быть равно нулю.

[in] hStore

Дескриптор хранилища, из которого выбираются сертификаты.

[out] pcSelection

Указатель на значение DWORD для получения количества элементов в массиве, на который указывает параметр pprgpSelection .

[out] pprgpSelection

Указатель на указатель на расположение для получения массива CERT_CHAIN_CONTEXT структуры. Функция CertSelectCertificateChains возвращает только цепочки сертификатов, которые соответствуют всем критериям выбора. Записи в массиве упорядочены по качеству, т. е. цепочка с наивысшим качеством является первой записью.

Хранилище для массива выделяется функцией CertSelectCertificateChains . Чтобы освободить выделенную память, необходимо сначала освободить каждый отдельный контекст цепочки в массиве, вызвав функцию CertFreeCertificateChain . Затем необходимо освободить память, вызвав функцию CertFreeCertificateChainList .

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

Если функция выполняется успешно, функция возвращает значение TRUE.

Если функция завершается сбоем, она возвращает ноль (FALSE). Для получения дополнительных сведений об ошибке вызовите функцию GetLastError .

Примечание Если выбор не дает никаких результатов, функция CertSelectCertificateChains возвращает значение TRUE, но значение, на которое указывает параметр pcSelection , равно нулю.
 

Комментарии

Критерии выбора можно указать с помощью параметра dwFlags , с помощью параметра rgpCriteria или с помощью обоих параметров. Если критерии выбора не указаны, функция выполняется успешно и возвращает цепочки сертификатов для всех сертификатов в хранилище, указанном параметром hStore .

Выбранные цепочки сертификатов упорядочены на основе следующей логики предпочтений:

  • Отдавайте предпочтение сертификатам, которые являются смарт-карта, а не сертификатам, которые не основаны на смарт-карта.
  • Предпочитать сертификаты с более длительным сроком действия (дата окончания срока действия позже).
  • Если несколько сертификатов имеют одинаковую дату окончания срока действия, отдавайте предпочтение сертификатам, которые были выданы совсем недавно.
  • Если есть галстук, отдавайте предпочтение более коротким цепям.
Для выбора определенных критериев выбора необходимо создать цепочку сертификатов, прежде чем вы сможете выбрать эти критерии для использования. Если промежуточные сертификаты, необходимые для построения цепочки, недоступны локально, для сертификатов издателя выполняется сетевое извлечение. Этот сетевой поиск выполняется, если установлен флаг CERT_SELECT_TRUSTED_ROOT или для следующих условий:
  • CERT_SELECT_BY_ISSUER_NAME
  • CERT_SELECT_BY_ISSUER_ATTR
  • CERT_SELECT_BY_POLICY_OID
Выполните следующие действия, чтобы включить проверку строгой сигнатуры:

При включении проверки строгой подписи любая цепочка сертификатов, возвращающая ошибку CERT_TRUST_IS_NOT_SIGNATURE_VALID в поле dwErrorStatusструктуры CERT_TRUST_STATUS , будет пропущена. (Параметр pprgpSelection указывает на структуру CERT_CHAIN_CONTEXT , которая, в свою очередь, указывает на структуру CERT_TRUST_STATUS .) Значение CERT_TRUST_HAS_WEAK_SIGNATURE также устанавливается для слабой сигнатуры.

Требования

Требование Значение
Минимальная версия клиента Windows 7 [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2008 R2 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header wincrypt.h
Библиотека Crypt32.lib
DLL Crypt32.dll

См. также раздел

CertGetCertificateContextProperty

CertSetCertificateContextProperty