CertGetCertificateChain 함수(wincrypt.h)
CertGetCertificateChain 함수는 최종 인증서에서 시작하여 가능한 경우 신뢰할 수 있는 루트 인증서로 돌아가는 인증서 체인 컨텍스트를 빌드합니다.
구문
BOOL CertGetCertificateChain(
[in, optional] HCERTCHAINENGINE hChainEngine,
[in] PCCERT_CONTEXT pCertContext,
[in, optional] LPFILETIME pTime,
[in] HCERTSTORE hAdditionalStore,
[in] PCERT_CHAIN_PARA pChainPara,
[in] DWORD dwFlags,
[in] LPVOID pvReserved,
[out] PCCERT_CHAIN_CONTEXT *ppChainContext
);
매개 변수
[in, optional] hChainEngine
사용할 체인 엔진(네임스페이스 및 캐시)의 핸들입니다. hChainEngine이 NULL인 경우 HCCE_CURRENT_USER 기본 체인 엔진이 사용됩니다. 이 매개 변수는 HCCE_LOCAL_MACHINE 설정할 수 있습니다.
[in] pCertContext
체인이 빌드되는 인증서인 최종 인증서의 CERT_CONTEXT 대한 포인터입니다. 이 인증서 컨텍스트는 첫 번째 단순 체인의 인덱스 요소가 아닙니다.
[in, optional] pTime
체인의 유효성을 검사할 시간을 나타내는 FILETIME 변수에 대한 포인터입니다. 시간은 신뢰 목록, 해지 또는 루트 저장소 검사에 영향을 주지 않습니다. NULL이 이 매개 변수에 전달되는 경우 현재 시스템 시간이 사용됩니다. 신뢰할 수 있는 루트인 특정 인증서에 대한 신뢰는 루트 저장소의 현재 상태를 기반으로 하며 이 매개 변수에 의해 전달된 시간에 루트 저장소의 상태가 아닙니다. 해지의 경우 CRL( 인증서 해지 목록 ) 자체는 현재 시간에 유효해야 합니다. 이 매개 변수의 값은 CRL에 나열된 인증서가 해지되었는지 여부를 확인하는 데 사용됩니다.
[in] hAdditionalStore
지원 인증서 및 CTL( 인증서 신뢰 목록 )을 검색하는 추가 저장소에 대한 핸들입니다. 검색할 추가 저장소가 없는 경우 이 매개 변수는 NULL 일 수 있습니다.
[in] pChainPara
체인 빌드 매개 변수를 포함하는 CERT_CHAIN_PARA 구조체에 대한 포인터입니다.
[in] dwFlags
특수 처리를 나타내는 값에 플래그를 지정합니다. 이 매개 변수는 다음 플래그 중 하나 이상의 조합일 수 있습니다.
| 값 | 의미 |
|---|---|
|
이 플래그를 설정하면 최종 인증서가 캐시되므로 체인 빌드 프로세스의 속도가 빨라집니다. 기본적으로 최종 인증서는 캐시되지 않으며 체인을 빌드할 때마다 확인해야 합니다. |
|
해지 확인은 캐시된 URL에만 액세스합니다. |
|
이 플래그는 순환 해지 검사를 방지하기 위해 OCSP(온라인 인증서 상태 프로토콜) 서명자 인증서에 대해 체인을 빌드하는 동안 내부적으로 사용됩니다. 체인 빌드 중에 OCSP 응답이 독립적인 OCSP 서명자에 의해 서명된 경우 원래 체인 빌드 외에도 OCSP 서명자 인증서 자체에 대해 빌드된 두 번째 체인이 있습니다. 이 플래그는 재귀적인 독립 OCSP 서명자 인증서를 억제하기 위해 이 두 번째 체인 빌드 중에 사용됩니다. 서명자 인증서에 szOID_PKIX_OCSP_NOCHECK 확장이 포함된 경우 리프 서명자 인증서에 대한 해지 검사를 건너뜁니다. OCSP 및 CRL 검사가 모두 허용됩니다.
Windows Server 2003 및 Windows XP: 이 값은 지원되지 않습니다. |
|
인증서 체인을 빌드할 때 캐시된 URL만 사용합니다. 인터넷 및 인트라넷은 URL 기반 개체를 검색하지 않습니다.
참고 이 플래그는 해지 검사에 적용되지 않습니다. 해지 검사에 캐시된 URL만 사용하도록 CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY 설정합니다. |
|
성능상의 이유로 체인 빌드의 두 번째 패스는 첫 번째 패스 중에 결정된 최고 품질보다 크거나 같은 품질의 잠재적 체인 경로만 고려합니다. 첫 번째 패스는 유효한 서명, 전체 체인 및 신뢰할 수 있는 루트만 고려하여 체인 품질을 계산합니다. 이 플래그는 이 최적화를 사용하지 않도록 설정하고 두 번째 패스 중에 모든 잠재적 체인 경로를 고려하도록 설정할 수 있습니다. |
|
이 플래그는 지원되지 않습니다. "내" 저장소의 인증서는 피어 트러스트로 간주되지 않습니다. |
|
"TrustedPeople" 저장소의 최종 엔터티 인증서는 체인 빌드를 수행하지 않고 신뢰할 수 있습니다. 이 함수는 ppChainContext 매개 변수의 CERT_TRUST_IS_PARTIAL_CHAIN 또는 CERT_TRUST_IS_UNTRUSTED_ROOTdwErrorStatus 멤버 비트를 설정하지 않습니다. Windows Server 2003 Windows XP: 이 플래그는 지원되지 않습니다. |
|
이 플래그를 설정하면 호출자가 약한 서명 검사를 옵트인하려고 합니다.
이 플래그는 Windows 7 및 Windows Server 2008 R2부터 각 OS에 대한 롤업 업데이트에서 사용할 수 있습니다. |
|
기본값은 최고 품질의 체인 경로만 반환하는 것입니다. 이 플래그를 설정하면 품질이 낮은 체인이 반환됩니다. 체인 컨텍스트의 cLowerQualityChainContext 및 rgpLowerQualityChainContext 필드에 반환됩니다. |
|
이 플래그를 설정하면 Windows 업데이트 웹 서버에서 타사 루트의 자동 업데이트가 금지됩니다. |
|
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT 설정하고 CERT_CHAIN_PARA 구조체의 dwUrlRetrievalTimeout 멤버에 대한 값도 지정하는 경우 dwUrlRetrievalTimeout에서 지정하는 값은 모든 해지 URL 검색에 대한 누적 시간 제한을 나타냅니다.
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT 설정했지만 dwUrlRetrievalTimeout 값을 지정하지 않으면 최대 누적 시간 제한이 기본적으로 20초로 설정됩니다. 테스트된 각 URL은 나머지 누적 잔액의 절반이 통과된 후 시간 초과됩니다. 즉, 첫 번째 URL은 10초 후, 두 번째 URL은 5초 후, 세 번째 URL은 2.5초 이후 시간 초과되고, URL이 성공하거나, 20초가 지나거나, 더 이상 테스트할 URL이 없습니다. CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT 설정하지 않으면 체인의 각 해지 URL에 dwUrlRetrievalTimeout에 지정된 값과 동일한 최대 시간 제한이 할당됩니다. dwUrlRetrievalTimeout 멤버에 대한 값을 지정하지 않으면 각 해지 URL에 최대 기본 시간 제한인 15초가 할당됩니다. URL이 성공하지 못하면 최대 누적 시간 제한 값은 15초에 체인의 URL 수를 곱합니다. 그룹 정책 사용하여 기본값을 설정할 수 있습니다. |
|
이 플래그를 설정하면 pTime 이 타임스탬프를 사용하여 최종 인증서가 시간 유효한지 여부를 확인합니다. 현재 시간을 사용하여 최종 인증서가 유효한 시간으로 유지되는지 여부를 확인할 수도 있습니다. 체인의 다른 모든 CA( 인증 기관 ) 및 루트 인증서는 pTime이 아닌 현재 시간을 사용하여 확인됩니다. |
|
이 플래그를 설정하면 AIA(기관 정보 액세스) 검색이 명시적으로 해제됩니다. |
다음 해지 플래그를 설정할 수도 있지만 이 그룹의 플래그는 한 번에 하나만 설정할 수 있습니다.
[in] pvReserved
이 매개 변수는 예약되어 있으며 NULL이어야 합니다.
[out] ppChainContext
생성된 체인 컨텍스트에 대한 포인터의 주소입니다. 체인 컨텍스트 사용을 마쳤으면 CertFreeCertificateChain 함수를 호출하여 체인을 해제합니다.
반환 값
함수가 성공하면 함수는 0이 아닌 값(TRUE)을 반환합니다.
함수가 실패하면 0(FALSE)을 반환합니다. 확장 오류 정보는 GetLastError를 호출합니다.
설명
애플리케이션이 인증서 체인을 요청하면 반환되는 구조체는 CERT_CHAIN_CONTEXT 형식입니다. 이 컨텍스트에는 각 단순 체인이 최종 인증서에서 자체 서명된 인증서로 가는 CERT_SIMPLE_CHAIN 구조의 배열이 포함되어 있습니다. 체인 컨텍스트는 신뢰 목록을 통해 간단한 체인을 연결합니다. 각 단순 체인에는 인증서 체인, 체인에 대한 요약 신뢰 정보 및 체인의 각 인증서 요소에 대한 신뢰 정보가 포함됩니다.
다음 설명은 강력한 서명 검사에 적용됩니다.
- pChainPara 매개 변수가 가리키는 CERT_CHAIN_PARA 구조체의 pStrongSignPara 멤버를 설정하여 이 함수에 대한 강력한 서명 검사를 사용하도록 설정할 수 있습니다.
- 체인에 강력한 서명이 없는 인증서가 있으면 CERT_TRUST_HAS_WEAK_SIGNATURE 및 CERT_TRUST_IS_NOT_SIGNATURE_VALID 오류가 CERT_TRUST_STATUS 구조체의 dwErrorStatus 필드에 설정됩니다. ppChainContext 매개 변수는 CERT_TRUST_STATUS 구조를 가리키는 CERT_CHAIN_CONTEXT 구조를 가리킵니다.
- 체인이 강력한 서명된 경우 최종 인증서의 공개 키를 확인하여 강력한 서명에 대한 최소 공개 키 길이 요구 사항을 충족하는지 여부를 확인합니다. 조건이 충족되지 않으면 CERT_TRUST_STATUS 구조체의 dwErrorStatus 필드에 CERT_TRUST_HAS_WEAK_SIGNATURE 및 CERT_TRUST_IS_NOT_SIGNATURE_VALID 오류가 설정됩니다. 키 길이 확인을 사용하지 않으려면 pChainPara 매개 변수가 가리키는 CERT_CHAIN_PARA 구조체의 dwStrongSignFlags 멤버에서 CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG 값을 설정합니다.
- CERT_STRONG_SIGN_ENABLE_CRL_CHECK 또는 CERT_STRONG_SIGN_ENABLE_OCSP_CHECK 플래그가 CERT_STRONG_SIGN_SERIALIZED_INFO 구조에 설정되어 있고 강력한 서명 없이 CRL 또는 OCSP 응답이 발견되면 CRL 또는 OCSP 응답은 오프라인으로 처리됩니다. 즉, CERT_TRUST_IS_OFFLINE_REVOCATION 및 CERT_TRUST_REVOCATION_STATUS_UNKNOWN 오류는 CERT_TRUST_STATUS 구조체의 dwErrorStatus 필드에 설정됩니다. 또한 CERT_REVOCATION_INFO 구조체의 dwRevocationResult 멤버는 NTE_BAD_ALGID 설정됩니다.
예제
이 함수를 사용하는 예제는 예제 C 프로그램: 인증서 체인 만들기를 참조하세요.
요구 사항
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | wincrypt.h |
| 라이브러리 | Crypt32.lib |
| DLL | Crypt32.dll |
추가 정보
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기