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 사용을 결정합니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.
| 값 | 의미 |
|---|---|
|
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로 설정된 경우 키 사용 확장 또는 속성이 없는 인증서도 일치합니다. 이 플래그를 설정하면 pvFindPara에서 NULL을 전달하는 것이 우선합니다. 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_ATTRpszObjId 멤버가 NULL이면 특성 개체 식별자는 무시됩니다. CERT_RDN_ATTR dwValueType 멤버가 CERT_RDN_ANY_TYPE 경우 값 형식은 무시됩니다. CERT_RDN_VALUE_BLOBpbData 멤버가 NULL이면 모든 값이 일치합니다. 현재는 대/소문자를 구분하는 정확한 일치만 지원됩니다. 유니코드 옵션에 대한 자세한 내용은 비고를 참조하세요. 이러한 값을 설정하면 인코딩 형식이 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 변수입니다.
pvFindPara의 DWORD 값으로 지정된 속성 식별자와 일치하는 속성이 있는 인증서를 검색합니다. |
|
pvFindPara의 데이터 형식: 구조체를 CERT_PUBLIC_KEY_INFO.
CERT_PUBLIC_KEY_INFO 구조의 공개 키와 일치하는 공개 키가 있는 인증서를 검색합니다. |
|
pvFindPara의 데이터 형식: CRYPT_HASH_BLOB 구조체입니다.
CRYPT_HASH_BLOB 구조의 해시와 일치하는 SHA1 해시가 있는 인증서를 검색합니다. |
|
pvFindPara의 데이터 형식: 구조체를 CRYPT_HASH_BLOB.
CRYPT_HASH_BLOB 구조의 서명 해시와 일치하는 서명 해시가 있는 인증서를 검색합니다. |
|
pvFindPara의 데이터 형식: 구조체를 CERT_RDN.
CERT_RDN 구조의 특성과 일치하는 지정된 주체 특성이 있는 인증서를 검색합니다. RDN 값이 설정된 경우 함수는 인증서의 주체 특성을 이 CERT_RDN 구조의 CERT_RDN_ATTR 배열 요소와 비교합니다. 비교는 인증서의 주체 특성과 일치하는 CERT_RDN_ATTR 특성을 반복합니다. CERT_RDN_ATTRpszObjId 멤버가 NULL이면 특성 개체 식별자는 무시됩니다. CERT_RDN_ATTR dwValueType 멤버가 CERT_RDN_ANY_TYPE 경우 값 형식은 무시됩니다. CERT_RDN_VALUE_BLOBpbData 멤버가 NULL이면 모든 값이 일치합니다. 현재는 대/소문자를 구분하는 정확한 일치만 지원됩니다. 유니코드 옵션에 대한 자세한 내용은 비고를 참조하세요. 이러한 값을 설정하면 인코딩 형식이 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 이어야 합니다. 검색 조건을 충족하는 연속 인증서를 찾으려면 pPrevCertContext 를 함수에 대한 이전 호출에서 반환된 포인터로 설정합니다. 이 함수는 이 매개 변수의 NULL이 아닌 값에서 참조하는 CERT_CONTEXT 해제합니다.
반환 값
함수가 성공하면 함수는 읽기 전용 CERT_CONTEXT 구조체에 대한 포인터를 반환합니다.
함수가 실패하고 검색 조건과 일치하는 인증서를 찾을 수 없는 경우 반환 값은 NULL입니다.
CertFindCertificateInStore가 반환하는 NULL이 아닌 CERT_CONTEXTCertFreeCertificateContext에서 해제하거나 CertFindCertificateInStore에 대한 후속 호출에서 pPrevCertContext 매개 변수로 전달되어야 합니다.
확장된 오류 정보는 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 를 호출하여 반환된 컨텍스트를 복제할 수 있습니다. 반환된 컨텍스트는 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 |
추가 정보
CertAddCertificateContextToStore
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기