다음을 통해 공유


CertFindCertificateInStore 함수(wincrypt.h)

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

사용되는 인코딩 유형을 지정합니다. 인증서 및 메시지 인코딩 형식은 다음 예제와 같이 비트OR 작업과 결합하여 지정해야 합니다.

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING 현재 정의된 인코딩 형식은 다음과 같습니다.

  • X509_ASN_ENCODING
  • PKCS_7_ASN_ENCODING

[in] dwFindFlags

검색 조건을 수정하기 위해 일부 dwFindType 값과 함께 사용됩니다. 대부분의 dwFindType 값의 경우 dwFindFlags 사용되지 않으며 0으로 설정해야 합니다. 자세한 내용은 비고를 참조하세요.

[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 확장이 있는 인증서 또는 CTL_USAGE 구조의 pszUsageIdentifier 멤버와 일치하는 CERT_CTL_PROP_ID 검색합니다.

CERT_FIND_ENHKEY_USAGE
pvFindPara데이터 형식: CERT_ENHKEY_USAGE 구조체입니다.

CERT_ENHKEY_USAGE 구조의 cUsageIdentifier 멤버와 일치하는 향상된 키 사용량 확장 또는 향상된 키 사용량 속성 및 사용 식별자가 있는 저장소에서 인증서를 검색합니다.

pszObjId 멤버가 szOID_ENHANCED_KEY_USAGE 설정된 CERT_EXTENSION 구조가 있는 경우 인증서에는 향상된 키 사용 확장이 있습니다.

인증서의 CERT_ENHKEY_USAGE_PROP_ID 식별자가 설정된 경우 인증서에 향상된 키 사용 속성이 있습니다.

CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG dwFindFlags설정된 경우 키 사용 확장 또는 속성이 없는 인증서도 일치합니다. 이 플래그를 설정하면 pvFindParaNULL 전달보다 우선합니다.

CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG 설정되면 키 사용 확장에서만 일치가 수행됩니다.

검색 조건에 대한 플래그 수정에 대한 자세한 내용은 비고를 참조하세요.

CERT_FIND_EXISTING
pvFindPara데이터 형식: CERT_CONTEXT 구조체입니다.

지정된 인증서 컨텍스트와 정확히 일치하는 인증서를 검색합니다.

CERT_FIND_HASH
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.

CRYPT_HASH_BLOB 구조의 해시와 일치하는 SHA1 해시가 있는 인증서를 검색합니다.

CERT_FIND_HAS_PRIVATE_KEY
pvFindPara데이터 형식: NULL사용되지 않습니다.

프라이빗 키가 있는 인증서를 검색합니다. 키는 임시 키이거나 디스크에 저장할 수 있습니다. 키는 레거시 CAPI(Cryptography API) 키 또는 CNG 키일 수 있습니다.

참고 인증서 컨텍스트의 순서는 저장소 내에서 유지되지 않을 수 있습니다. 따라서 특정 인증서에 액세스하려면 모든 인증서를 반복해야 합니다.
 
Windows 8 및 Windows Server 2012: 이 플래그에 대한 지원이 시작됩니다.
CERT_FIND_ISSUER_ATTR
pvFindPara데이터 형식: CERT_RDN 구조체입니다.

CERT_RDN 구조의 특성과 일치하는 지정된 발급자 특성이 있는 인증서를 검색합니다. 이러한 값을 설정하면 이 함수는 인증서에서 발급자의 특성을 이 CERT_RDN 구조의 CERT_RDN_ATTR 배열 요소와 비교합니다. 비교는 인증서의 발급자 특성과 일치하는 항목을 찾는 CERT_RDN_ATTR 특성을 반복합니다.

CERT_RDN_ATTR pszObjId 멤버가 NULL경우 특성 개체 식별자는 무시됩니다.

CERT_RDN_ATTRdwValueType 멤버가 CERT_RDN_ANY_TYPE 경우 값 형식은 무시됩니다.

CERT_RDN_VALUE_BLOB pbData 멤버가 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로 끝나는 유니코드 문자열입니다.

지정된 발급자 이름 문자열이 포함된 인증서를 검색합니다. 인증서의 발급자 멤버는 CERT_SIMPLE_NAME_STR 형식의 적절한 형식의 CertNameToStr 사용하여 적절한 형식의 이름 문자열로 변환됩니다. 그런 다음 대/소문자를 구분하지 않는 부분 문자열 내 일치가 수행됩니다. 이 값을 설정하면 인코딩 형식이 dwCertEncodingType일치하는 인증서로 검색이 제한됩니다.

부분 문자열 일치가 실패하고 제목에 Punycode로 인코딩된 문자열이 있는 이메일 RDN이 포함된 경우 CERT_NAME_STR_ENABLE_PUNYCODE_FLAG 제목을 유니코드 문자열로 변환하는 데 사용되고 부분 문자열 일치가 다시 수행됩니다.

CERT_FIND_KEY_IDENTIFIER
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.

CRYPT_HASH_BLOB키 식별자와 일치하는 CERT_KEY_IDENTIFIER_PROP_ID 속성이 있는 인증서를 검색합니다.

CERT_FIND_KEY_SPEC
pvFindPara데이터 형식: 키 사양이 포함된 DWORD 변수입니다.

pvFindPara키 사양과 일치하는 CERT_KEY_SPEC_PROP_ID 속성이 있는 인증서를 검색합니다.

CERT_FIND_MD5_HASH
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.

CRYPT_HASH_BLOB해시와 일치하는 MD5 해시가 있는 인증서를 검색합니다.

CERT_FIND_PROPERTY
pvFindPara데이터 형식: 속성 식별자를 포함하는 DWORD 변수입니다.

pvFindParaDWORD 값으로 지정된 속성 식별자와 일치하는 속성이 있는 인증서를 검색합니다.

CERT_FIND_PUBLIC_KEY
pvFindPara데이터 형식: CERT_PUBLIC_KEY_INFO 구조체입니다.

CERT_PUBLIC_KEY_INFO 구조의 공개 키와 일치하는 공개 키가 있는 인증서를 검색합니다.

CERT_FIND_SHA1_HASH
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.

CRYPT_HASH_BLOB 구조의 해시와 일치하는 SHA1 해시가 있는 인증서를 검색합니다.

CERT_FIND_SHA1_SHA256_HASH
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.

CRYPT_HASH_BLOB 구조의 해시와 일치하는 SHA1 + SHA256 해시가 있는 인증서를 검색합니다.

CERT_FIND_SHA256_HASH
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.

CRYPT_HASH_BLOB 구조의 해시와 일치하는 SHA256 해시가 있는 인증서를 검색합니다.

CERT_FIND_SIGNATURE_HASH
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.

CRYPT_HASH_BLOB 구조의 서명 해시와 일치하는 서명 해시가 있는 인증서를 검색합니다.

CERT_FIND_SUBJECT_ATTR
pvFindPara데이터 형식: CERT_RDN 구조체입니다.

CERT_RDN 구조의 특성과 일치하는 지정된 주체 특성이 있는 인증서를 검색합니다. RDN 값이 설정된 경우 함수는 인증서의 주체 특성을 이 CERT_RDN 구조의 CERT_RDN_ATTR 배열 요소와 비교합니다. 비교는 인증서의 주체 특성과 일치하는 항목을 찾는 CERT_RDN_ATTR 특성을 반복합니다.

CERT_RDN_ATTR pszObjId 멤버가 NULL경우 특성 개체 식별자는 무시됩니다.

CERT_RDN_ATTRdwValueType 멤버가 CERT_RDN_ANY_TYPE 경우 값 형식은 무시됩니다.

CERT_RDN_VALUE_BLOB pbData 멤버가 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로 끝나는 유니코드 문자열입니다.

지정된 주체 이름 문자열이 포함된 인증서를 검색합니다. 인증서의 주체 멤버는 CERT_SIMPLE_NAME_STR 형식이 지정된 적절한 형식의 CertNameToStr 사용하여 적절한 형식의 이름 문자열로 변환됩니다. 그런 다음 대/소문자를 구분하지 않는 부분 문자열 내 일치가 수행됩니다. 이 값을 설정하면 인코딩 형식이 dwCertEncodingType일치하는 인증서로 검색이 제한됩니다.

CERT_FIND_CROSS_CERT_DIST_POINTS
pvFindPara데이터 형식: 사용되지 않습니다.

인증서 간 배포 지점 확장 또는 속성이 있는 인증서를 찾습니다.

CERT_FIND_PUBKEY_MD5_HASH
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.

MD5 해시 공개 키가 지정된 해시와 일치하는 인증서를 찾습니다.

 
참고pvFindPara문자열을 전달하는 dwFindType 값의 대체 형식이 있습니다. 한 폼은 유니코드 문자열을 사용하고 다른 하나는 ASCII 문자열을 사용합니다. "_W"로 끝나거나 접미사가 없는 값은 유니코드를 사용합니다. "_A"로 끝나는 값은 ASCII 문자열을 사용합니다.
 

[in] pvFindPara

dwFindType사용하는 데이터 항목 또는 구조를 가리킵니다.

[in] pPrevCertContext

이 함수에서 반환된 마지막 CERT_CONTEXT 구조체에 대한 포인터입니다. 이 매개 변수는 함수의 첫 번째 호출에서 NULL 합니다. 검색 조건을 충족하는 연속 인증서를 찾으려면 pPrevCertContext 함수에 대한 이전 호출에서 반환된 포인터로 설정합니다. 이 함수는 이 매개 변수의 비NULL 값에서 참조하는 CERT_CONTEXT 해제합니다.

반환 값

함수가 성공하면 함수는 읽기 전용 CERT_CONTEXT 구조체에 대한 포인터를 반환합니다.

함수가 실패하고 검색 조건과 일치하는 인증서를 찾을 수 없는 경우 반환 값은 NULL.

certFindCertificateInStore 반환을 NULLCERT_CONTEXT CertFreeCertificateContext 또는 CertFindCertificateInStore대한 후속 호출에서 pPrevCertContext 매개 변수로 전달되어야 합니다.

확장 오류 정보는 GetLastError호출합니다. 몇 가지 가능한 오류 코드는 다음과 같습니다.

반환 코드 묘사
CRYPT_E_NOT_FOUND
검색 조건과 일치하는 인증서를 찾을 수 없습니다. 이 문제는 저장소가 비어 있거나 저장소 목록의 끝에 도달한 경우에 발생할 수 있습니다.
E_INVALIDARG
hCertStore 매개 변수의 핸들은 인증서 컨텍스트pPrevCertContext 매개 변수가 가리키는 것과 동일하지 않거나 dwFindType 매개 변수에 유효하지 않은 값이 지정되었습니다.

발언

dwFindFlags 매개 변수는 일부 검색 형식의 조건을 수정하는 데 사용됩니다.

CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags 값은 dwFindType대한 CERT_FIND_SUBJECT_ATTR 및 CERT_FIND_ISSUER_ATTR 값에만 사용됩니다. pvFindPara 가리키는 CERT_RDN_ATTR 구조체가 유니코드 문자열로 초기화된 경우 CERT_UNICODE_IS_RDN_ATTRS_FLAG 설정해야 합니다. 비교하기 전에 일치시킬 문자열은 X509_UNICODE_NAME 사용하여 유니코드 비교를 제공하여 변환됩니다.

다음 dwFindFlags 값은 dwFindType대한 CERT_FIND_ENKEY_USAGE 값에만 사용됩니다.

CertDuplicateCertificateContext 호출하여 반환된 컨텍스트를 복제할 수 있습니다. 반환된 컨텍스트는 CertAddCertificateContextToStore사용하여 다른 인증서 저장소에 추가할 수 있습니다. 또는 CertAddCertificateLinkToStore사용하여 컬렉션 저장소가 아닌 저장소에 해당 인증서 컨텍스트에 대한 링크를 추가할 수 있습니다.

반환된 포인터는 함수에 대한 후속 호출에서 pPrevCertContext 매개 변수로 전달될 때 해제됩니다. 그렇지 않으면 CertFreeCertificateContext호출하여 포인터를 명시적으로 해제해야 합니다. NULL 않는 pPrevCertContext 함수에 오류가 있더라도 CertFreeCertificateContext호출을 사용하여 CertFindCertificateInStore 항상 해제됩니다.

예제

다음 예제에서는 검색 조건을 충족하는 인증서 저장소에서 인증서 컨텍스트를 찾는 방법을 보여줍니다. 이 예제의 컨텍스트를 포함하는 전체 예제는 예제 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
헤더 wincrypt.h
라이브러리 Crypt32.lib
DLL Crypt32.dll

참고 항목

CERT_CONTEXT

CertAddCertificateContextToStore

CertAddCertificateLinkToStore

CertDuplicateCertificateContext

CertEnumCertificatesInStore

CertFreeCertificateContext

CertGetCertificateChain

CertNameToStr

인증서 함수