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

Статья
06/24/2024

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

Синтаксис

PCCERT_CONTEXT CertFindCertificateInStore(
  [in] HCERTSTORE     hCertStore,
  [in] DWORD          dwCertEncodingType,
  [in] DWORD          dwFindFlags,
  [in] DWORD          dwFindType,
  [in] const void     *pvFindPara,
  [in] PCCERT_CONTEXT pPrevCertContext
);

Параметры

[in] hCertStore

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

[in] dwCertEncodingType

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

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

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFindFlags

Используется с некоторыми значениями dwFindType dwFindType для изменения условий поиска. Для большинства значений dwFindTypedwFindFlags не используется и должен иметь значение нулю. Подробные сведения см. в разделе "Примечания".

[in] dwFindType

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

Ценность	Значение
CERT_FIND_ANY	Тип данных pvFindPara: NULL, не используется. Критерии поиска не используются. Возвращает следующий сертификат в хранилище. Примечание Порядок контекста сертификата может не сохраняться в хранилище. Чтобы получить доступ к конкретному сертификату, необходимо выполнить итерацию по сертификатам в хранилище.
CERT_FIND_CERT_ID	Тип данных pvFindPara: CERT_ID структура. Найдите сертификат, определенный указанным CERT_ID.
CERT_FIND_CTL_USAGE	Тип данных pvFindPara: структура CTL_USAGE. Ищет сертификат, имеющий расширение szOID_ENHANCED_KEY_USAGE или CERT_CTL_PROP_ID, соответствующий pszUsageIdentifier элементу структуры CTL_USAGE.
CERT_FIND_ENHKEY_USAGE	Тип данных pvFindPara: структура CERT_ENHKEY_USAGE. Ищет сертификат в хранилище с расширенным использованием ключей или расширенным свойством использования ключа и идентификатором использования, соответствующим элементу cUsageIdentifier в структуре CERT_ENHKEY_USAGE. Сертификат имеет расширение расширенного использования ключа, если у него есть структура CERT_EXTENSION с pszObjId, для szOID_ENHANCED_KEY_USAGE. Сертификат имеет свойство расширенного использования ключа, если задан его идентификатор CERT_ENHKEY_USAGE_PROP_ID. Если CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG задан в dwFindFlags, сертификаты без расширения использования ключа или свойства также совпадают. Установка этого флага имеет приоритет над передачей NULL в pvFindPara. Если CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG задано, совпадение выполняется только в расширении использования ключа. Сведения об изменениях флагов в критерии поиска см. в примечаниях.
CERT_FIND_EXISTING	Тип данных pvFindPara: структура CERT_CONTEXT. Выполняет поиск сертификата, точного соответствия заданного контекста сертификата.
CERT_FIND_HASH	Тип данных pvFindPara: структура CRYPT_HASH_BLOB. Ищет сертификат с хэшом SHA1, который соответствует хэшу в структуре CRYPT_HASH_BLOB.
CERT_FIND_HAS_PRIVATE_KEY	Тип данных pvFindPara: NULL, не используется. Ищет сертификат с закрытым ключом. Ключ может быть временным или сохраненным на диске. Ключ может быть устаревшим ключом API шифрования (CAPI) или ключом CNG. Примечание Порядок контекста сертификата может не сохраняться в хранилище. Таким образом, чтобы получить доступ к конкретному сертификату, необходимо выполнить итерацию по всем сертификатам. Windows 8 и Windows Server 2012: начинается поддержка этого флага .
CERT_FIND_ISSUER_ATTR	Тип данных pvFindPara: структура CERT_RDN. Выполняет поиск сертификата с указанными атрибутами издателя, которые соответствуют атрибутам в структуре CERT_RDN. Если эти значения заданы, функция сравнивает атрибуты издателя в сертификате с элементами массива CERT_RDN_ATTR в этой структуре CERT_RDN. Сравнение выполняется по CERT_RDN_ATTR атрибутам, которые ищут совпадение с атрибутами издателя сертификата. Если CERT_RDN_ATTR элемент pszObjId NULL, идентификатор объекта атрибута игнорируется. Если элемент dwValueTypeCERT_RDN_ATTR CERT_RDN_ANY_TYPE, тип значения игнорируется. Если элемент CERT_RDN_VALUE_BLOB pbData имеет значение NULL NULL, любое значение совпадает. В настоящее время поддерживается только точное совпадение с учетом регистра. Сведения о параметрах Юникода см. в разделе "Примечания". Если эти значения заданы, поиск ограничен сертификатами, тип кодирования которых соответствует dwCertEncodingType.
CERT_FIND_ISSUER_NAME	Тип данных pvFindPara: структура CERT_NAME_BLOB. Выполните поиск сертификата с точным совпадением всего имени издателя с именем в CERT_NAME_BLOB Поиск ограничен сертификатами, которые соответствуют dwCertEncodingType.
CERT_FIND_ISSUER_OF	Тип данных pvFindPara: структура CERT_CONTEXT. Выполняет поиск сертификата с темой, которая соответствует издателю в CERT_CONTEXT. Вместо использования CertFindCertificateInStore с этим значением используйте функцию CertGetCertificateChain.
CERT_FIND_ISSUER_STR	Тип данных pvFindPara: строка Юникода, завершаемая null. Ищет сертификат, содержащий указанную строку имени издателя. Член издателя сертификата преобразуется в строку имени соответствующего типа, используя соответствующую форму CertNameToStr отформатированную как CERT_SIMPLE_NAME_STR. Затем выполняется сопоставление подстроки в строке без учета регистра. Если это значение задано, поиск ограничен сертификатами, тип кодирования которых соответствует dwCertEncodingType. Если совпадение подстроки завершается ошибкой, и тема содержит RDN электронной почты с закодированной строкой Punycode, CERT_NAME_STR_ENABLE_PUNYCODE_FLAG используется для преобразования темы в строку Юникода, и сопоставление подстроки выполняется снова.
CERT_FIND_KEY_IDENTIFIER	Тип данных pvFindPara: структура CRYPT_HASH_BLOB. Выполняет поиск сертификата со свойством CERT_KEY_IDENTIFIER_PROP_ID, которое соответствует идентификатору ключа в CRYPT_HASH_BLOB.
CERT_FIND_KEY_SPEC	Тип данных pvFindPara: переменная DWORD, содержащая спецификацию ключа. Ищет сертификат, имеющий свойство CERT_KEY_SPEC_PROP_ID, соответствующее спецификации ключа в pvFindPara.
CERT_FIND_MD5_HASH	Тип данных pvFindPara: структура CRYPT_HASH_BLOB. Выполняет поиск сертификата с хэшом MD5, который соответствует хэшу в CRYPT_HASH_BLOB.
CERT_FIND_PROPERTY	Тип данных pvFindPara: переменная DWORD, содержащая идентификатор свойства. Выполняет поиск сертификата со свойством, соответствующим идентификатору свойства, заданному значением DWORD в pvFindPara.
CERT_FIND_PUBLIC_KEY	Тип данных pvFindPara: структура CERT_PUBLIC_KEY_INFO. Ищет сертификат с открытым ключом, который соответствует открытому ключу в структуре CERT_PUBLIC_KEY_INFO.
CERT_FIND_SHA1_HASH	Тип данных pvFindPara: структура CRYPT_HASH_BLOB. Ищет сертификат с хэшом SHA1, который соответствует хэшу в структуре CRYPT_HASH_BLOB.
CERT_FIND_SHA1_SHA256_HASH	Тип данных pvFindPara: структура CRYPT_HASH_BLOB. Ищет сертификат с хэшом SHA1, который соответствует хэшу в структуре CRYPT_HASH_BLOB.
CERT_FIND_SHA256_HASH	Тип данных pvFindPara: структура CRYPT_HASH_BLOB. Ищет сертификат с хэшом SHA1, который соответствует хэшу в структуре CRYPT_HASH_BLOB.
CERT_FIND_SIGNATURE_HASH	Тип данных pvFindPara: структура CRYPT_HASH_BLOB. Ищет сертификат с хэшом подписи, который соответствует хэшу подписи в структуре CRYPT_HASH_BLOB.
CERT_FIND_SUBJECT_ATTR	Тип данных pvFindPara: структура CERT_RDN. Выполняет поиск сертификата с указанными атрибутами субъекта, которые соответствуют атрибутам в структуре CERT_RDN. Если заданы значения RDN, функция сравнивает атрибуты субъекта в сертификате с элементами массива CERT_RDN_ATTR в этой структуре CERT_RDN. Сравнение выполняется по CERT_RDN_ATTR атрибутам, которые ищут совпадение с атрибутами субъекта сертификата. Если CERT_RDN_ATTR элемент pszObjId NULL, идентификатор объекта атрибута игнорируется. Если элемент dwValueTypeCERT_RDN_ATTR CERT_RDN_ANY_TYPE, тип значения игнорируется. Если элемент CERT_RDN_VALUE_BLOB pbData имеет значение NULL NULL, любое значение совпадает. В настоящее время поддерживается только точное совпадение с учетом регистра. Сведения о параметрах Юникода см. в разделе "Примечания". Если эти значения заданы, поиск ограничен сертификатами, тип кодирования которых соответствует dwCertEncodingType.
CERT_FIND_SUBJECT_CERT	Тип данных pvFindPara: структура CERT_INFO. Выполняет поиск сертификата с издателем и серийным номером, соответствующим издателю и серийному номеру в структуре CERT_INFO.
CERT_FIND_SUBJECT_NAME	Тип данных pvFindPara: структура CERT_NAME_BLOB. Выполняет поиск сертификата с точным совпадением всего имени субъекта с именем в структуре CERT_NAME_BLOB. Поиск ограничен сертификатами, соответствующими значению dwCertEncodingType.
CERT_FIND_SUBJECT_STR	Тип данных pvFindPara: строка Юникода, завершаемая null. Ищет сертификат, содержащий указанную строку имени субъекта. Член субъекта сертификата преобразуется в строку имени соответствующего типа, используя соответствующую форму CertNameToStr отформатированную как CERT_SIMPLE_NAME_STR. Затем выполняется сопоставление подстроки в строке без учета регистра. Если это значение задано, поиск ограничен сертификатами, тип кодирования которых соответствует dwCertEncodingType.
CERT_FIND_CROSS_CERT_DIST_POINTS	Тип данных pvFindPara: не используется. Найдите сертификат с расширением или свойством точки распространения кросс-сертификатов.
CERT_FIND_PUBKEY_MD5_HASH	Тип данных pvFindPara: структура CRYPT_HASH_BLOB. Найдите сертификат, хэш-хэш которого MD5 соответствует указанному хэшу.

Примечание Существуют альтернативные формы значения dwFindType, которые передают строку в pvFindPara. Одна форма использует строку Юникода, а другая — строку ASCII. Значения, заканчивающиеся на "_W" или без суффикса, используют Юникод. Значения, заканчивающиеся _A, используют строки ASCII.

[in] pvFindPara

Указывает на элемент данных или структуру, используемую с dwFindType.

[in] pPrevCertContext

Указатель на последнюю CERT_CONTEXT структуру, возвращаемую этой функцией. Этот параметр должен быть null при первом вызове функции. Чтобы найти последовательные сертификаты, соответствующие условиям поиска, задайте pPrevCertContext указатель, возвращаемый предыдущим вызовом функции. Эта функция освобождает CERT_CONTEXT, на которые ссылается неNULL значений этого параметра.

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

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

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

НеNULLCERT_CONTEXT, которые возвращать CertFindCertificateInStore, должны быть освобождены CertFreeCertificateContext или передается в качестве параметра pPrevCertContext при последующем вызове CertFindCertificateInStore.

Для получения расширенных сведений об ошибке вызовите GetLastError. Ниже приведены некоторые возможные коды ошибок.

Возвращаемый код	Описание
CRYPT_E_NOT_FOUND	Сертификат не найден в соответствии с критериями поиска. Это может произойти, если хранилище пусто или достигается конец списка магазина.
E_INVALIDARG	Дескриптор в параметре hCertStore не совпадает с тем, что в контексте сертификата , на который указывает параметр pPrevCertContext или недопустимое значение, указанное в параметре dwFindType.

Замечания

Параметр dwFindFlags используется для изменения условий некоторых типов поиска.

Значение dwFindFlags CERT_UNICODE_IS_RDN_ATTRS_FLAG используется только со значениями CERT_FIND_SUBJECT_ATTR и CERT_FIND_ISSUER_ATTR для dwFindType. CERT_UNICODE_IS_RDN_ATTRS_FLAG необходимо задать, если структура CERT_RDN_ATTR, на которую указывает pvFindPara, была инициализирована строками Юникода. Перед выполнением сравнения строка, которую нужно сопоставить, преобразуется с помощью X509_UNICODE_NAME для сравнения Юникода.

Следующие значения dwFindFlags используются только со значением CERT_FIND_ENKEY_USAGE для dwFindType:

CertDuplicateCertificateContext можно вызвать, чтобы создать дубликат возвращаемого контекста. Возвращаемый контекст можно добавить в другое хранилище сертификатов с помощью CertAddCertificateContextToStoreили ссылку на этот контекст сертификата можно добавить в хранилище, которое не является хранилищем коллекций, с помощью CertAddCertificateLinkToStore.

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

Примеры

В следующем примере показано, как найти контекст сертификата в хранилище сертификатов, удовлетворяющий критерию поиска. Полный пример, содержащий контекст для этого примера, см. в разделе Пример программы C: операции хранилища сертификатов.

Другой пример, использующий эту функцию, см. в разделе Пример программы C: операции сбора и брата хранилища сертификатов.

#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")

#define MY_ENCODING_TYPE  (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)

void main()
{
//-------------------------------------------------------------------
// Declare and initialize variables.
HCERTSTORE  hSystemStore;              // The system store handle.
PCCERT_CONTEXT  pDesiredCert = NULL;   // Set to NULL for the first 
                                       // call to
                                       // CertFindCertificateInStore.
LPCSTR lpszCertSubject = (LPCSTR) "Cert_subject_1";


//-------------------------------------------------------------------
// Open the certificate store to be searched.

if(hSystemStore = CertOpenStore(
     CERT_STORE_PROV_SYSTEM, 
     0,                      // Encoding type not needed 
                             // with this PROV.
     NULL,                   // Accept the default HCRYPTPROV. 
     CERT_SYSTEM_STORE_CURRENT_USER,
                             // Set the system store location in 
                             // the registry.
     L"MY"))                 // Could have used other predefined 
                             // system stores
                             // including Trust, CA, or Root.
{
   printf("Opened the MY system store. \n");
}
else
{
   printf( "Could not open the MY system store.\n");
   exit(1);
}
//-------------------------------------------------------------------
// Get a certificate that has lpszCertSubject as its 
// subject. 

if(pDesiredCert=CertFindCertificateInStore(
      hSystemStore,
      MY_ENCODING_TYPE,           // Use X509_ASN_ENCODING.
      0,                          // No dwFlags needed. 
      CERT_FIND_SUBJECT_STR,      // Find a certificate with a
                                  // subject that matches the string
                                  // in the next parameter.
      lpszCertSubject ,           // The Unicode string to be found
                                  // in a certificate's subject.
      NULL))                      // NULL for the first call to the
                                  // function. In all subsequent
                                  // calls, it is the last pointer
                                  // returned by the function.
{
  printf("The desired certificate was found. \n");
}
else
{
   printf("Could not find the desired certificate.\n");
}
//-------------------------------------------------------------------
// Clean up. 

if(pDesiredCert)
    CertFreeCertificateContext(pDesiredCert);
if(hSystemStore)
    CertCloseStore(
        hSystemStore, 
        CERT_CLOSE_STORE_CHECK_FLAG);

Требования

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