CertFindCertificateInStore 함수(wincrypt.h)
통사론
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 사용되지 않으며 0으로 설정해야 합니다. 자세한 내용은 비고를 참조하세요.
[in] dwFindType
검색할 형식을 지정합니다. 검색 유형은 데이터 형식, 콘텐츠 및 pvFindPara사용을 결정합니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.
| 값 | 의미 |
|---|---|
|
pvFindPara데이터 형식: NULL사용되지 않습니다.
검색 조건이 사용되지 않습니다. 저장소에서 다음 인증서를 반환합니다.
참고 인증서 컨텍스트의 순서는 저장소 내에서 유지되지 않을 수 있습니다.
특정 인증서에 액세스하려면 저장소의 인증서를 반복해야 합니다.
|
|
pvFindPara데이터 형식: CERT_ID 구조체입니다.
지정된 CERT_ID식별된 인증서를 찾습니다. |
|
pvFindPara데이터 형식: CTL_USAGE 구조체입니다.
szOID_ENHANCED_KEY_USAGE 확장이 있는 인증서 또는 CTL_USAGE 구조의 pszUsageIdentifier 멤버와 일치하는 CERT_CTL_PROP_ID 검색합니다. |
|
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 설정되면 키 사용 확장에서만 일치가 수행됩니다. 검색 조건에 대한 플래그 수정에 대한 자세한 내용은 비고를 참조하세요. |
|
pvFindPara데이터 형식: CERT_CONTEXT 구조체입니다.
지정된 인증서 컨텍스트와 정확히 일치하는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.
CRYPT_HASH_BLOB 구조의 해시와 일치하는 SHA1 해시가 있는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: NULL사용되지 않습니다.
프라이빗 키가 있는 인증서를 검색합니다. 키는 임시 키이거나 디스크에 저장할 수 있습니다. 키는 레거시 CAPI(Cryptography API) 키 또는 CNG 키일 수 있습니다.
참고 인증서 컨텍스트의 순서는 저장소 내에서 유지되지 않을 수 있습니다. 따라서 특정 인증서에 액세스하려면 모든 인증서를 반복해야 합니다.
|
|
pvFindPara데이터 형식: CERT_RDN 구조체입니다.
CERT_RDN 구조의 특성과 일치하는 지정된 발급자 특성이 있는 인증서를 검색합니다. 이러한 값을 설정하면 이 함수는 인증서에서 발급자의 특성을 이 CERT_RDN 구조의 CERT_RDN_ATTR 배열 요소와 비교합니다. 비교는 인증서의 발급자 특성과 일치하는 항목을 찾는 CERT_RDN_ATTR 특성을 반복합니다. CERT_RDN_ATTRdwValueType 멤버가 CERT_RDN_ANY_TYPE 경우 값 형식은 무시됩니다. 현재는 대/소문자를 구분하는 정확한 일치만 지원됩니다. 유니코드 옵션에 대한 자세한 내용은 비고를 참조하세요. 이러한 값을 설정하면 인코딩 형식이 dwCertEncodingType |
|
pvFindPara데이터 형식: CERT_NAME_BLOB 구조체입니다.
전체 발급자 이름과 이름이 정확히 일치하는 인증서를 검색합니다CERT_NAME_BLOB 검색은 dwCertEncodingType일치하는 인증서로 제한됩니다. |
|
pvFindPara데이터 형식: CERT_CONTEXT 구조체입니다.
CERT_CONTEXT발급자와 일치하는 주체가 있는 인증서를 검색합니다. 이 값으로 CertFindCertificateInStore 사용하는 대신 CertGetCertificateChain 함수를 사용합니다. |
|
pvFindPara데이터 형식: Null로 끝나는 유니코드 문자열입니다.
지정된 발급자 이름 문자열이 포함된 인증서를 검색합니다. 인증서의 발급자 멤버는 CERT_SIMPLE_NAME_STR 형식의 적절한 형식의 CertNameToStr 사용하여 적절한 형식의 이름 문자열로 변환됩니다. 그런 다음 대/소문자를 구분하지 않는 부분 문자열 내 일치가 수행됩니다. 이 값을 설정하면 인코딩 형식이 dwCertEncodingType 부분 문자열 일치가 실패하고 제목에 Punycode로 인코딩된 문자열이 있는 이메일 RDN이 포함된 경우 CERT_NAME_STR_ENABLE_PUNYCODE_FLAG 제목을 유니코드 문자열로 변환하는 데 사용되고 부분 문자열 일치가 다시 수행됩니다. |
|
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.
CRYPT_HASH_BLOB키 식별자와 일치하는 CERT_KEY_IDENTIFIER_PROP_ID 속성이 있는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: 키 사양이 포함된 DWORD 변수입니다.
pvFindPara키 사양과 일치하는 CERT_KEY_SPEC_PROP_ID 속성이 있는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.
CRYPT_HASH_BLOB해시와 일치하는 MD5 해시가 있는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: 속성 식별자를 포함하는 DWORD 변수입니다.
pvFindParaDWORD 값으로 지정된 속성 식별자와 일치하는 속성이 있는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: CERT_PUBLIC_KEY_INFO 구조체입니다.
CERT_PUBLIC_KEY_INFO 구조의 공개 키와 일치하는 공개 키가 있는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.
CRYPT_HASH_BLOB 구조의 해시와 일치하는 SHA1 해시가 있는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.
CRYPT_HASH_BLOB 구조의 해시와 일치하는 SHA1 + SHA256 해시가 있는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.
CRYPT_HASH_BLOB 구조의 해시와 일치하는 SHA256 해시가 있는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.
CRYPT_HASH_BLOB 구조의 서명 해시와 일치하는 서명 해시가 있는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: CERT_RDN 구조체입니다.
CERT_RDN 구조의 특성과 일치하는 지정된 주체 특성이 있는 인증서를 검색합니다. RDN 값이 설정된 경우 함수는 인증서의 주체 특성을 이 CERT_RDN 구조의 CERT_RDN_ATTR 배열 요소와 비교합니다. 비교는 인증서의 주체 특성과 일치하는 항목을 찾는 CERT_RDN_ATTR 특성을 반복합니다. CERT_RDN_ATTRdwValueType 멤버가 CERT_RDN_ANY_TYPE 경우 값 형식은 무시됩니다. 현재는 대/소문자를 구분하는 정확한 일치만 지원됩니다. 유니코드 옵션에 대한 자세한 내용은 비고를 참조하세요. 이러한 값을 설정하면 인코딩 형식이 dwCertEncodingType |
|
pvFindPara데이터 형식: CERT_INFO 구조체입니다.
CERT_INFO 구조의 발급자 및 일련 번호와 일치하는 발급자 및 일련 번호가 모두 있는 인증서를 검색합니다. |
|
pvFindPara데이터 형식: CERT_NAME_BLOB 구조체입니다.
전체 주체 이름과 CERT_NAME_BLOB 구조의 이름과 정확히 일치하는 인증서를 검색합니다. 검색은 dwCertEncodingType값과 일치하는 인증서로 제한됩니다. |
|
pvFindPara데이터 형식: Null로 끝나는 유니코드 문자열입니다.
지정된 주체 이름 문자열이 포함된 인증서를 검색합니다. 인증서의 주체 멤버는 CERT_SIMPLE_NAME_STR 형식이 지정된 적절한 형식의 CertNameToStr 사용하여 적절한 형식의 이름 문자열로 변환됩니다. 그런 다음 대/소문자를 구분하지 않는 부분 문자열 내 일치가 수행됩니다. 이 값을 설정하면 인코딩 형식이 dwCertEncodingType |
|
pvFindPara데이터 형식: 사용되지 않습니다.
인증서 간 배포 지점 확장 또는 속성이 있는 인증서를 찾습니다. |
|
pvFindPara데이터 형식: CRYPT_HASH_BLOB 구조체입니다.
MD5 해시 공개 키가 지정된 해시와 일치하는 인증서를 찾습니다. |
[in] pvFindPara
dwFindType사용하는 데이터 항목 또는 구조를 가리킵니다.
[in] pPrevCertContext
이 함수에서 반환된 마지막 CERT_CONTEXT 구조체에 대한 포인터입니다. 이 매개 변수는 함수의 첫 번째 호출에서 NULL
반환 값
함수가 성공하면 함수는 읽기 전용 CERT_CONTEXT 구조체에 대한 포인터를 반환합니다.
함수가 실패하고 검색 조건과 일치하는 인증서를 찾을 수 없는 경우 반환 값은 NULL
certFindCertificateInStore 반환을
확장 오류 정보는 GetLastError호출합니다. 몇 가지 가능한 오류 코드는 다음과 같습니다.
| 반환 코드 | 묘사 |
|---|---|
|
검색 조건과 일치하는 인증서를 찾을 수 없습니다. 이 문제는 저장소가 비어 있거나 저장소 목록의 끝에 도달한 경우에 발생할 수 있습니다. |
|
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 호출하여 반환된 컨텍스트를 복제할 수 있습니다. 반환된 컨텍스트는
반환된 포인터는 함수에 대한 후속 호출에서 pPrevCertContext 매개 변수로 전달될 때 해제됩니다. 그렇지 않으면 CertFreeCertificateContext호출하여 포인터를 명시적으로 해제해야 합니다. NULL
예제
다음 예제에서는 검색 조건을 충족하는 인증서 저장소에서 인증서 컨텍스트를 찾는 방법을 보여줍니다. 이 예제의 컨텍스트를 포함하는 전체 예제는 예제 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 |
참고 항목
CertAddCertificateContextToStore