CertFindCTLInStore 함수(wincrypt.h)

아티클
08/27/2023

CertFindCTLInStore 함수는 dwFindType 및 관련 pvFindPara에 의해 설정된 검색 조건과 일치하는 첫 번째 또는 다음 CTL(인증서 신뢰 목록) 컨텍스트를 찾습니다. 이 함수는 루프에서 사용하여 지정된 찾기 조건과 일치하는 인증서 저장소 의 모든 CTL 컨텍스트를 찾을 수 있습니다.

구문

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

매개 변수

[in] hCertStore

검색할 인증서 저장소의 핸들입니다.

[in] dwMsgAndCertEncodingType

CTL에 사용되는 인코딩 유형을 지정합니다. 다음 예제와 같이 비트 OR 작업과 결합하여 인증서 및 메시지 인코딩 형식을 모두 지정할 수 있습니다.

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

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

이 매개 변수는 dwFindType 매개 변수가 CTL_FIND_USAGE 설정된 경우에만 사용됩니다.

[in] dwFindFlags

dwFindType을 CTL_FIND_USAGE 설정할 때 설정할 수 있습니다. 자세한 내용은 CTL_FIND_USAGE 아래의 주석을 참조하세요.

[in] dwFindType

만들 검색 유형을 지정합니다. 검색 형식은 데이터 형식, 콘텐츠 및 pvFindPara 사용을 결정합니다. 이 매개 변수는 다음 값 중 하나일 수 있습니다.

값	의미
CTL_FIND_ANY	pvFindPara: NULL의 데이터 형식입니다. 모든 CTL은 일치합니다.
CTL_FIND_SHA1_HASH	pvFindPara의 데이터 형식: CRYPT_HASH_BLOB. CRYPT_HASH_BLOB 구조체의 해시와 일치하는 해시가 있는 CTL이 있습니다.
CTL_FIND_MD5_HASH	pvFindPara의 데이터 형식: CRYPT_HASH_BLOB. CRYPT_HASH_BLOB 구조체의 해시와 일치하는 해시가 있는 CTL이 있습니다.
CTL_FIND_USAGE	pvFindPara의 데이터 형식: CTL_FIND_USAGE_PARA. 사용 식별자, 목록 식별자 또는 서명자가 CTL_FIND_USAGE_PARA 구조의 사용 식별자, 목록 식별자 또는 서명자와 일치하는 CTL이 있습니다. cUsageIdentifier 멤버가 SubjectUsage 크기이면 CTL이 일치합니다. ListIdentifier 멤버의 cbData 멤버가 0이면 목록 식별자가 일치합니다. ListIdentifier의 cbData 멤버가 CTL_FIND_NO_LIST_ID_CBDATA 경우 목록 식별자가 없는 CTL만 일치합니다. CTL_FIND_USAGE_PARA 구조체의 pSigner 멤버가 NULL이면 CTL 서명자가 일치하며 pSignerCERT_INFO 구조체의 발급자 및 SerialNumber 멤버만 사용됩니다. pSigner가 CTL_FIND_NO_SIGNER_PTR 경우 서명자가 없는 CTL만 일치합니다.
CTL_FIND_SAME_USAGE_FLAG	pvFindPara의 데이터 형식: CTL_FIND_USAGE_PARA. 정확히 동일한 사용 식별자를 가진 CTL만 일치합니다. 추가 사용 식별자가 있는 CTL은 일치하지 않습니다. 예를 들어 CTL_FIND_USAGE_PARA 구조에 "1.2.3"만 지정된 경우 일치 항목의 경우 CTL에는 "1.2.3"만 포함되어야 하며 추가 사용 식별자는 없어야 합니다.
CTL_FIND_EXISTING	pvFindPara의 데이터 형식: PCCTL_CONTEXT. CTL_CONTEXT 정확히 일치하는 다음 CRL을 검색합니다.
CTL_FIND_SUBJECT	pvFindPara의 데이터 형식: CTL_FIND_SUBJECT_PARA. 지정된 제목이 있는 CTL을 찾습니다. CertFindSubjectInCTL 을 호출하여 CTL에서 주체의 항목에 대한 포인터를 가져올 수 있습니다. CTL_FIND_SUBJECT_PARApUsagePara 멤버는 CTL_FIND_USAGE 앞에서 설명한 일치를 사용하도록 선택적으로 설정할 수 있습니다.

[in] pvFindPara

dwFindType 매개 변수와 연결된 검색 값에 대한 포인터입니다.

[in] pPrevCtlContext

이 함수에서 반환한 마지막 CTL_CONTEXT 대한 포인터입니다. 저장소에서 첫 번째 CTL을 얻으려면 NULL 이어야 합니다. pPrevCtlContext를 이전 함수 호출에서 반환된 CTL_CONTEXT 대한 포인터로 설정하여 연속 CTL을 검색합니다. 검색 조건을 충족하지 않거나 CertDeleteCTLFromStore 에서 이전에 삭제한 인증서는 건너뜁니다. 이 함수는 이 매개 변수의 NULL이 아닌 값에서 참조하는 CTL_CONTEXT 해제합니다.

반환 값

함수가 성공하면 반환 값은 읽기 전용 CTL 컨텍스트에 대한 포인터입니다.

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

반환 코드	설명
CRYPT_E_NOT_FOUND	저장소에 CTL이 없거나 검색 조건과 일치하는 CTL이 없거나 함수가 저장소 목록의 끝에 도달했습니다.
E_INVALIDARG	hCertStore 매개 변수의 핸들은 pPrevCtlContext 매개 변수가 가리키는 CTL 컨텍스트의 핸들과 동일하지 않거나 유효하지 않은 값이 dwFindType 매개 변수에 지정되었습니다.

설명

반환된 포인터는 함수에 대한 후속 호출에서 pPrevCtlContext 로 전달될 때 해제됩니다. 그렇지 않으면 CertFreeCTLContext를 호출하여 포인터를 해제해야 합니다. 함수에 전달된 NULL이 아닌 pPrevCtlContext 는 함수가 오류를 생성하는 경우에도 CertFreeCTLContext를 호출하여 항상 해제됩니다.

CertDuplicateCTLContext 를 호출하여 반환된 컨텍스트를 복제할 수 있습니다. 반환된 CTL 컨텍스트는 CertAddCTLContextToStore를 사용하여 다른 인증서 저장소에 추가하거나 CertAddCTLLinkToStore를 사용하여 해당 CTL 컨텍스트에 대한 링크를 비콜렉션 저장소에 추가할 수 있습니다. 검색 조건과 일치하는 CTL을 찾을 수 없으면 NULL 이 반환됩니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	wincrypt.h
라이브러리	Crypt32.lib
DLL	Crypt32.dll