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

Статья
03/03/2024

Функция CertFindCTLInStore находит первый или следующий контекст списка доверия сертификатов (CTL), соответствующий условиям поиска, установленным dwFindType и связанной с ним pvFindPara. Эту функцию можно использовать в цикле для поиска всех контекстов CTL в хранилище сертификатов , соответствующих указанным критериям поиска.

Синтаксис

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

Параметры

[in] hCertStore

Дескриптор хранилища сертификатов для поиска.

[in] dwMsgAndCertEncodingType

Указывает тип кодировки, используемой в CTL. Всегда допустимо указывать типы кодирования сертификатов и сообщений, объединяя их с побитовой операцией ИЛИ , как показано в следующем примере:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING в настоящее время определены следующие типы кодирования:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

Этот параметр используется, только если параметру dwFindType присвоено значение CTL_FIND_USAGE.

[in] dwFindFlags

Можно задать, если параметру dwFindType присвоено значение CTL_FIND_USAGE. Дополнительные сведения см. в примечаниях в разделе CTL_FIND_USAGE ниже.

[in] dwFindType

Указывает тип выполняемого поиска. Тип поиска определяет тип данных, содержимое и использование pvFindPara. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
CTL_FIND_ANY	Тип данных pvFindPara: NULL. Любой CTL является совпадением.
CTL_FIND_SHA1_HASH	Тип данных pvFindPara: CRYPT_HASH_BLOB. Найден объект CTL с хэшом, соответствующим хэшу, в CRYPT_HASH_BLOB структуре.
CTL_FIND_MD5_HASH	Тип данных pvFindPara: CRYPT_HASH_BLOB. Найден объект CTL с хэшом, соответствующим хэшу, в CRYPT_HASH_BLOB структуре.
CTL_FIND_USAGE	Тип данных pvFindPara: CTL_FIND_USAGE_PARA. Обнаружен любой список CTL с идентификатором использования, идентификатором списка или подписывателем, соответствующим идентификатору использования, идентификатору списка или подписывшему элементу в структуре CTL_FIND_USAGE_PARA . Если член cUsageIdentifier имеет размер SubjectUsage , любой CTL является совпадением. Если элемент cbData элемента ListIdentifier равен нулю, любой идентификатор списка является совпадением. Если элемент cbDatalistIdentifier CTL_FIND_NO_LIST_ID_CBDATA, совпадением будет только CTL без идентификатора списка. Если элемент pSigner в структуре CTL_FIND_USAGE_PARA имеет значение NULL, любой подписывающий CTL является совпадением, и используются только члены Issuer и SerialNumber в структуре pSignerCERT_INFO . Если pSigner имеет CTL_FIND_NO_SIGNER_PTR, совпадением будет только CTL без подписывателя.
CTL_FIND_SAME_USAGE_FLAG	Тип данных pvFindPara: CTL_FIND_USAGE_PARA. Сопоставляются только списки CCL с одинаковыми идентификаторами использования. Списки CCL с дополнительными идентификаторами использования не совпадают. Например, если в структуре CTL_FIND_USAGE_PARA указан только "1.2.3", то для соответствия CTL должен содержать только "1.2.3" и не содержать дополнительных идентификаторов использования.
CTL_FIND_EXISTING	Тип данных pvFindPara: PCCTL_CONTEXT. Выполняет поиск следующего списка отзыва сертификатов, точно соответствующего CTL_CONTEXT.
CTL_FIND_SUBJECT	Тип данных pvFindPara: CTL_FIND_SUBJECT_PARA. Найден объект CTL с указанным субъектом. Можно вызвать CertFindSubjectInCTL , чтобы получить указатель на запись субъекта в CTL. При необходимости можно задать элемент pUsagePara в CTL_FIND_SUBJECT_PARA , чтобы включить сопоставление, описанное выше в разделе CTL_FIND_USAGE.

[in] pvFindPara

Указатель на значение поиска, связанное с параметром dwFindType .

[in] pPrevCtlContext

Указатель на последний CTL_CONTEXT , возвращенный этой функцией. Чтобы получить первый CTL в хранилище, он должен иметь значение NULL . Последовательные CCL извлекаются путем установки pPrevCtlContext указателя на CTL_CONTEXT , возвращенный предыдущим вызовом функции. Все сертификаты, не соответствующие условиям поиска или ранее удаленные CertDeleteCTLFromStore , пропускаются. Эта функция освобождает CTL_CONTEXT , на которые ссылаются значения этого параметра, отличные от NULL .

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

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

Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError. Ниже приведены некоторые возможные коды ошибок.

Код возврата	Описание
CRYPT_E_NOT_FOUND	Либо в магазине не было найдено списков CTL, соответствующих условиям поиска, либо функция достигла конца списка магазина.
E_INVALIDARG	Дескриптор в параметре hCertStore отличается от дескриптора в контексте CTL, на который указывает параметр pPrevCtlContext , или недопустимое значение было указано в параметре dwFindType .

Возвращаемый указатель освобождается при передаче в качестве pPrevCtlContext при последующем вызове функции. В противном случае указатель должен быть освобожден путем вызова CertFreeCTLContext. PPrevCtlContext, передаваемый в функцию, не имеющий значения NULL, всегда освобождается с помощью вызова CertFreeCTLContext, даже если функция создает ошибку.

Можно вызвать CertDuplicateCTLContext , чтобы создать дубликат возвращаемого контекста. Возвращаемый контекст CTL можно добавить в другое хранилище сертификатов с помощью CertAddCTLContextToStore, или ссылку на этот контекст CTL можно добавить в хранилище без коллекций с помощью CertAddCTLLinkToStore. Если не найден объект CTL, соответствующий условиям поиска, возвращается значение NULL .

Требования

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