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

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

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

[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 프로그램 예제: 인증서 체인만들기를 참조하세요.

요구 사항

참고 항목

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

인증서 체인 확인 함수