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

Статья
03/15/2023

Функция 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параметр dwFindFlags не используется и должен иметь нулевое значение. Подробные сведения см. в разделе Примечания.

[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 атрибуты , которые ищут совпадение с атрибутами издателя сертификата. Если элемент pszObjIdCERT_RDN_ATTR имеет значение NULL, идентификатор объекта атрибута игнорируется. Если элемент dwValueTypeCERT_RDN_ATTR CERT_RDN_ANY_TYPE, тип значения игнорируется. Если элемент pbDataCERT_RDN_VALUE_BLOB имеет значение 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_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 в поисках соответствия атрибутам субъекта сертификата. Если элемент pszObjIdCERT_RDN_ATTR имеет значение NULL, идентификатор объекта атрибута игнорируется. Если элемент dwValueTypeCERT_RDN_ATTR является CERT_RDN_ANY_TYPE, тип значения игнорируется. Если элемент pbDataCERT_RDN_VALUE_BLOB имеет значение 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.

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

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

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

Значение CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags используется только с значениями 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]
Целевая платформа	Windows
Header	wincrypt.h
Библиотека	Crypt32.lib
DLL	Crypt32.dll