다음을 통해 공유

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

사용할 체인 엔진(네임스페이스 및 캐시)의 핸들입니다. hChainEngineNULL경우 기본 체인 엔진인 HCCE_CURRENT_USER사용됩니다. 이 매개 변수는 HCCE_LOCAL_MACHINE설정할 수 있습니다.

[in] pCertContext

체인이 빌드되는 인증서인 최종 인증서의 CERT_CONTEXT 대한 포인터입니다. 이 인증서 컨텍스트는 첫 번째 단순 체인의 인덱스 0 요소가 됩니다.

[in, optional] pTime

체인의 유효성을 검사할 시간을 나타내는 FILETIME 변수에 대한 포인터입니다. 시간은 신뢰 목록, 해지 또는 루트 저장소 검사에 영향을 주지 않습니다. 현재 시스템 시간은 NULL 이 매개 변수에 전달되는 경우에 사용됩니다. 신뢰할 수 있는 루트인 특정 인증서에 대한 신뢰는 루트 저장소의 현재 상태 기반으로 하며 이 매개 변수에서 전달된 시간에 루트 저장소의 상태가 아닙니다. 해지의 경우 CRL(인증서 해지 목록) 자체는 현재 시간에 유효해야 합니다. 이 매개 변수의 값은 CRL에 나열된 인증서가 해지되었는지 여부를 확인하는 데 사용됩니다.

[in] hAdditionalStore

지원 인증서를 검색하고 인증서 신뢰 목록(CTL)을 추가 저장소에 대한 핸들입니다. 이 매개 변수는 검색할 추가 저장소가 없는 경우 NULL 수 있습니다.

[in] pChainPara

체인 빌드 매개 변수를 포함하는 CERT_CHAIN_PARA 구조체에 대한 포인터입니다.

[in] dwFlags

특수 처리를 나타내는 값에 플래그를 지정합니다. 이 매개 변수는 다음 플래그 중 하나 이상의 조합일 수 있습니다.

값 의미
CERT_CHAIN_CACHE_END_CERT
0x00000001		 이 플래그를 설정하면 최종 인증서가 캐시되므로 체인 빌드 프로세스의 속도가 빨라질 수 있습니다. 기본적으로 최종 인증서는 캐시되지 않으며 체인을 빌드할 때마다 확인해야 합니다.
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
0x80000000		 해지 확인은 캐시된 URL에만 액세스합니다. 이렇게 하면 최종 또는 CA 인증서에 대한 CRL 또는 OCSP의 네트워크 검색을 방지할 수 있습니다. CACHE_ONLY 네트워크에서 CRL 또는 OCSP를 이미 검색한 컴퓨터의 친구에 따라 달라집니다.
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT
0x04000000		 이 플래그는 순환 해지 검사를 방지하기 위해 OCSP(온라인 인증서 상태 프로토콜) 서명자 인증서에 대해 체인을 빌드하는 동안 내부적으로 사용됩니다. 체인 빌드 중에 OCSP 응답이 독립적인 OCSP 서명자에 의해 서명된 경우 원래 체인 빌드 외에도 OCSP 서명자 인증서 자체에 대해 빌드된 두 번째 체인이 있습니다. 이 플래그는 이 두 번째 체인 빌드 중에 재귀 독립적인 OCSP 서명자 인증서를 억제하는 데 사용됩니다. 서명자 인증서에 szOID_PKIX_OCSP_NOCHECK 확장이 포함되어 있으면 리프 서명자 인증서에 대한 해지 검사를 건너뜁니다. OCSP 및 CRL 검사는 모두 허용됩니다.

Windows Server 2003 및 Windows XP: 이 값은 지원되지 않습니다.
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
0x00000004		 인증서 체인을 빌드할 때 캐시된 URL만 사용합니다. 인터넷 및 인트라넷은 CTL cabs, 타사 루트 및 AIA 발급자와 같은 URL 기반 개체를 검색하지 않습니다. 대부분의 루트는 crypt32.dll 리소스에 있어야 합니다. 그렇지 않은 경우 체인 빌드 오류를 방지하기 위해 이 검색이 필요합니다. 이러한 cabs 및 루트는 고성능 Microsoft CDN 서버에서 호스트됩니다.

참고: 이 플래그는 해지 검사에 적용되지 않습니다. 해지 확인에 캐시된 URL만 사용하도록 CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY 설정합니다. 일반적으로 CTL cabs는 이미 cryptsvc 서비스를 통해 미리 인출되어 있습니다.
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING0x00000040 성능상의 이유로 체인 빌드의 두 번째 패스는 첫 번째 패스 중에 결정된 최고 품질보다 크거나 같은 잠재적인 체인 경로만 고려합니다. 첫 번째 패스는 유효한 서명, 전체 체인 및 신뢰할 수 있는 루트만 고려하여 체인 품질을 계산합니다. 이 플래그를 설정하여 이 최적화를 사용하지 않도록 설정하고 두 번째 패스 중에 모든 잠재적 체인 경로를 고려할 수 있습니다.
CERT_CHAIN_DISABLE_MY_PEER_TRUST
0x00000800		 이 플래그는 지원되지 않습니다. "내" 저장소의 인증서는 피어 트러스트로 간주되지 않습니다.
CERT_CHAIN_ENABLE_PEER_TRUST
0x00000400		 "TrustedPeople" 저장소의 최종 엔터티 인증서는 체인 빌드를 수행하지 않고 신뢰할 수 있습니다. 이 함수는 ppChainContext 매개 변수의 CERT_TRUST_IS_PARTIAL_CHAIN 또는 CERT_TRUST_IS_UNTRUSTED_ROOTdwErrorStatus 멤버 비트를 설정하지 않습니다.

Windows Server 2003 및 Windows XP: 이 플래그는 지원되지 않습니다.
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE
0x00010000		 이 플래그를 설정하면 호출자가 약한 서명 검사를 옵트인하려고 합니다.

이 플래그는 Windows 7 및 Windows Server 2008 R2부터 각 OS에 대한 롤업 업데이트에서 사용할 수 있습니다.
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS
0x00000080		 기본값은 최고 품질의 체인 경로만 반환하는 것입니다. 이 플래그를 설정하면 품질이 낮은 체인이 반환됩니다. 체인 컨텍스트의 cLowerQualityChainContext 및 rgpLowerQualityChainContext 필드에 반환됩니다.
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE
0x00000100		 이 플래그를 설정하면 Windows 업데이트 웹 서버에서 타사 루트의 자동 업데이트가 금지됩니다.
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT
0x08000000		 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 수를 곱합니다.

그룹 정책을 사용하여 기본값을 설정할 수 있습니다.
CERT_CHAIN_TIMESTAMP_TIME
0x00000200		 이 플래그가 설정되면 pTime 타임스탬프를 사용하여 최종 인증서가 유효한 시간인지 여부를 확인합니다. 현재 시간을 사용하여 최종 인증서가 유효한 시간으로 유지되는지 여부를 확인할 수도 있습니다. 다른 모든 CA(인증 기관) 및 체인의 루트 인증서는 pTime아니라 현재 시간을 사용하여 확인됩니다.
CERT_CHAIN_DISABLE_AIA
0x00002000		 이 플래그를 설정하면 AIA(기관 정보 액세스) 검색이 명시적으로 해제됩니다. TLS 서버가 잘못 구성되고 핸드셰이크에 올바른 CA 인증서를 포함하지 않는 경우가 있습니다.

다음 해지 플래그를 설정할 수도 있지만 이 그룹의 플래그는 한 번에 하나만 설정할 수 있습니다.

값 의미
CERT_CHAIN_REVOCATION_CHECK_END_CERT
0x10000000		 해지 검사는 최종 인증서 및 최종 인증서에서만 수행됩니다.
CERT_CHAIN_REVOCATION_CHECK_CHAIN
0x20000000		 해지 검사는 모든 체인의 모든 인증서에서 수행됩니다.
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT
0x40000000		 해지 검사는 루트 인증서를 제외한 모든 체인의 모든 인증서에서 수행됩니다.

[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.

다음 권장 사항은 TLS 서버 인증 인증서를 확인하기 위해 이러한 API를 호출하는 모든 Windows 애플리케이션에 적용됩니다.

  • 최종 인증서에 대한 해지 검사만 사용하도록 설정합니다.
    • CERT_CHAIN_REVOCATION_CHECK_END_CERT 플래그를 설정합니다.
    • 대부분의 CA 인증서에는 1~6개월의 시간 유효성이 있는 CRL이 있습니다.
      • 다운로드한 CRL은 캐시되므로 이 유효성이 너무 길어 값이 너무 깁니다.
    • CA 손상이 있는 경우 인증서도 Windows 허용되지 않는 CTL에 추가됩니다.
    • TLS 서버에 권장되는 방법은 최종 인증서에 대한 OCSP 스테이플링을 지원하는 것입니다.
      • 이 경우 스테이플된 OCSP 응답이 만료되지 않는 한 네트워크 검색이 필요하지 않습니다.
  • CRL, OCSP, AIA 발급자 및 Windows 플랫폼 CTL cab 및 타사 루트에 대한 네트워크 검색을 사용하도록 설정합니다.
    • 위의 CERT_CHAIN_REVOCATION_CHECK_END_CERT 설정되면 기본값입니다.
    • 네트워크 검색을 방지하기 위해 다음 플래그를 설정하지 마세요. 이러한 플래그에 대한 자세한 내용은 위의 dwFlags 표를 참조하세요.
      • CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
      • CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
      • CERT_CHAIN_DISABLE_AIA
  • CRL 및 OCSP 네트워크 검색에 대해 누적 시간 제한을 사용하도록 설정합니다.
    • CertGetCertificateChain전달된 CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT 플래그를 설정합니다.
    • CRL 및 OCSP 네트워크 검색에 허용되는 총 시간에 대한 상한을 제공합니다.
  • 각 네트워크 검색에 허용되는 최대 시간을 15초에서 10초로 줄입니다.
    • CertGetCertificateChain 전달된 CERT_CHAIN_PARAdwUrlRetrievalTimeout 필드를 10 * 1000밀리초로 설정합니다.
    • 또한 누적 시간 제한을 20초에서 10초로 줄입니다.
      • 최종 인증서에 대해 OCSP 응답만 다운로드해야 합니다. 해당 다운로드에 대해 5초 정도면 충분합니다.
  • 오프라인 해지 오류를 무시합니다.
    • CertVerifyCertificateChainPolicy(CERT_CHAIN_POLICY_SSL)전달된 CERT_CHAIN_POLICY_PARACERT_CHAIN_POLICY_IGNORE_ALL_REV_UNKNOWN_FLAGS 설정합니다.
    • OCSP 및 CRL의 네트워크 검색이 가장 좋습니다. 대부분의 네트워크 검색은 몇 초 후에 성공해야 하지만 100개% 보장되지는 않습니다.
  • 캐시 끝 인증서 유효성 검사 정보입니다.
    • CERT_CHAIN_CACHE_END_CERT설정합니다.
      • 중간 인증서 외에도 최종 인증서에 대한 정보의 LRU 캐싱을 사용하도록 설정합니다.
    • 동일한 서버에 여러 TLS 연결을 만드는 것이 일반적입니다.

예제

이 함수를 사용하는 예제는 C 프로그램 예제: 인증서 체인만들기를 참조하세요.

요구 사항

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

참고 항목

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

인증서 체인 확인 함수