CertSelectCertificateChains 함수(wincrypt.h)

  • 아티클

CertSelectCertificateChains 함수는 지정된 선택 조건에 따라 인증서 체인을 검색합니다.

구문

BOOL CertSelectCertificateChains(
  [in, optional] LPCGUID                  pSelectionContext,
  [in]           DWORD                    dwFlags,
  [in, optional] PCCERT_SELECT_CHAIN_PARA pChainParameters,
  [in]           DWORD                    cCriteria,
  [in, optional] PCCERT_SELECT_CRITERIA   rgpCriteria,
  [in]           HCERTSTORE               hStore,
  [out]          PDWORD                   pcSelection,
  [out]          PCCERT_CHAIN_CONTEXT     **pprgpSelection
);

매개 변수

[in, optional] pSelectionContext

이 호출에 사용할 인증서 선택 시나리오의 GUID에 대한 포인터입니다.

[in] dwFlags

인증서 선택 프로세스를 제어하기 위한 플래그입니다. 이 매개 변수는 다음 플래그 중 0개 이상의 조합일 수 있습니다.

값 의미
CERT_SELECT_ALLOW_EXPIRED
 선택 조건을 충족하는 만료된 인증서를 선택합니다. 기본적으로 만료된 인증서는 선택에서 거부됩니다.
CERT_SELECT_TRUSTED_ROOT
 인증서 체인 트러스트 상태 오류 비트가 CERT_TRUST_IS_UNTRUSTED_ROOT, CERT_TRUST_IS_PARTIAL_CHAIN또는CERT_TRUST_IS_NOT_TIME_VALID 설정되지 않은 인증서를 선택합니다.

또한 다음 잘못된 제약 조건 오류 중 하나가 있는 인증서는 선택되지 않습니다.

  • CERT_TRUST_INVALID_POLICY_CONSTRAINTS
  • CERT_TRUST_INVALID_BASIC_CONSTRAINTS
  • CERT_TRUST_INVALID_NAME_CONSTRAINTS
CERT_SELECT_DISALLOW_SELFSIGNED
 자체 발급되지 않고 자체 서명되지 않은 인증서를 선택합니다.
CERT_SELECT_HAS_PRIVATE_KEY
 인증서의 CERT_KEY_PROV_INFO_PROP_ID 속성에 대한 값이 설정된 인증서를 선택합니다.
CERT_SELECT_HAS_KEY_FOR_SIGNATURE
 CERT_KEY_PROV_INFO_PROP_ID 속성의 dwKeySpec 멤버 값이 AT_SIGNATURE 설정된 인증서를 선택합니다.

이 함수가 CNG 사용 애플리케이션의 일부로 호출되고 CERT_KEY_PROV_INFO_PROP_ID 속성의 dwKeySpec 멤버가 -1로 설정된 경우 연결된 프라이빗 키의 NCRYPT_KEY_USAGE_PROPERTY 속성 값이 NCRYPT_ALLOW_SIGNING_FLAG 설정된 인증서를 선택합니다.
CERT_SELECT_HAS_KEY_FOR_KEY_EXCHANGE
 CERT_KEY_PROV_INFO_PROP_ID 속성의 dwKeySpec 멤버 값이 AT_KEYEXCHANGE 설정된 인증서를 선택합니다.

이 함수가 CNG 사용 애플리케이션의 일부로 호출되고 CERT_KEY_PROV_INFO_PROP_ID 속성의 dwKeySpec 멤버가 -1로 설정된 경우 NCRYPT_ALLOW_DECRYPT_FLAG 또는 NCRYPT_ALLOW_KEY_AGREEMENT_FLAG 설정된 인증서를 선택합니다.
CERT_SELECT_HARDWARE_ONLY
 연결된 프라이빗 키 공급자의 PP_IMPTYPE 속성 값이 CRYPT_IMPL_HARDWARE또는 CRYPT_IMPL_REMOVABLE 설정된 인증서를 선택합니다. CNG 공급자의 경우 NCRYPT_IMPL_TYPE_PROPERTY 속성 값에는 NCRYPT_IMPL_HARDWARE_FLAG 또는 NCRYPT_IMPL_REMOVABLE_FLAG 비트 집합이 있어야 합니다.

이 함수가 CNG 사용 애플리케이션의 일부로 호출되는 경우 NCRYPT_IMPL_TYPE_PROPERTY 속성이 NCRYPT_IMPL_HARDWARE_FLAG또는 NCRYPT_IMPL_REMOVABLE_FLAG 설정된 인증서를 선택합니다.
CERT_SELECT_ALLOW_DUPLICATES
 주체 및 주체 대체 이름에 동일한 정보가 포함되고 인증서 템플릿 확장 값이 동일한 인증서 선택을 허용합니다. 기본적으로 인증서가 이 조건과 일치하면 가장 최근의 인증서만 선택됩니다.

[in, optional] pChainParameters

체인 빌드에 대한 매개 변수를 지정하는 CERT_SELECT_CHAIN_PARA 구조체에 대한 포인터입니다. NULL인 경우 기본 매개 변수가 사용됩니다.

CERT_SELECT_CHAIN_PARA 구조체의 pChainPara 멤버는 강력한 서명을 사용하도록 설정하는 데 사용할 수 있는 CERT_CHAIN_PARA 구조를 가리킵니다.

[in] cCriteria

rgpCriteria 배열이 가리키는 배열의 요소 수입니다.

[in, optional] rgpCriteria

선택 조건을 정의하는 CERT_SELECT_CRITERIA 구조체 배열에 대한 포인터입니다. 이 매개 변수가 NULL로 설정된 경우 cCriteria 매개 변수의 값은 0이어야 합니다.

[in] hStore

인증서를 선택할 저장소에 대한 핸들입니다.

[out] pcSelection

pprgpSelection 매개 변수가 가리키는 배열의 요소 수를 수신하는 DWORD 값에 대한 포인터입니다.

[out] pprgpSelection

CERT_CHAIN_CONTEXT 구조체 배열을 받을 위치에 대한 포인터입니다. CertSelectCertificateChains 함수는 모든 선택 조건과 일치하는 인증서 체인만 반환합니다. 배열의 항목은 품질별로 정렬됩니다. 즉, 품질이 가장 높은 체인이 첫 번째 항목입니다.

배열에 대한 스토리지는 CertSelectCertificateChains 함수에 의해 할당됩니다. 할당된 메모리를 해제하려면 먼저 CertFreeCertificateChain 함수를 호출하여 배열의 각 개별 체인 컨텍스트를 해제해야 합니다. 그런 다음 CertFreeCertificateChainList 함수를 호출하여 메모리를 해제해야 합니다.

반환 값

함수가 성공하면 함수는 TRUE를 반환합니다.

함수가 실패하면 0(FALSE)을 반환합니다. 확장된 오류 정보는 GetLastError 함수를 호출합니다.

참고 선택 영역에서 결과가 생성되지 않으면 CertSelectCertificateChains 함수는 TRUE를 반환하지만 pcSelection 매개 변수가 가리키는 값은 0으로 설정됩니다.
 

설명

선택 조건은 dwFlags 매개 변수, rgpCriteria 매개 변수 또는 두 매개 변수를 통해 지정할 수 있습니다. 선택 조건을 지정하지 않으면 함수가 성공하고 hStore 매개 변수로 지정된 저장소의 모든 인증서에 대한 인증서 체인을 반환합니다.

선택한 인증서 체인은 다음 기본 설정 논리에 따라 정렬됩니다.

  • 스마트 카드 기반이 아닌 인증서보다 스마트 카드 인증서인 인증서를 선호합니다.
  • 유효 기간이 더 긴 인증서를 선호합니다(만료 날짜는 이후).
  • 여러 인증서의 만료 날짜가 같으면 최근에 발급된 인증서를 사용하는 것이 좋습니다.
  • 넥타이가 있는 경우 더 짧은 체인을 선호합니다.
특정 선택 조건을 사용하려면 해당 조건을 선택하기 전에 인증서 체인을 빌드해야 합니다. 체인을 빌드하는 데 필요한 중간 인증서를 로컬로 사용할 수 없는 경우 발급자 인증서에 대해 네트워크 검색이 수행됩니다. 이 네트워크 검색은 CERT_SELECT_TRUSTED_ROOT 플래그가 설정된 경우 또는 다음 조건에 대해 수행됩니다.
  • CERT_SELECT_BY_ISSUER_NAME
  • CERT_SELECT_BY_ISSUER_ATTR
  • CERT_SELECT_BY_POLICY_OID
강력한 서명 검사를 사용하도록 설정하려면 다음 작업을 수행합니다.
  • CERT_STRONG_SIGN_PARA 구조체를 만들고, 필요한 강력한 서명 매개 변수를 지정하고, CERT_CHAIN_PARA 구조체의 pStrongSignPara 멤버에서 구조체에 대한 포인터를 설정합니다.
  • CERT_SELECT_CHAIN_PARA 구조체의 pChainPara 멤버에서 CERT_CHAIN_PARA 구조체에 대한 포인터를 설정합니다.
  • 이(CertSelectCertificateChains) 함수의 pChainParameters 매개 변수에서 CERT_SELECT_CHAIN_PARA 구조체에 대한 포인터를 설정합니다.

강력한 서명 검사를 사용하도록 설정하면 CERT_TRUST_STATUS 구조의 dwErrorStatus 필드에서 CERT_TRUST_IS_NOT_SIGNATURE_VALID 오류를 반환하는 인증서 체인은 건너뜁히게 됩니다. (pprgpSelection 매개 변수는 CERT_CHAIN_CONTEXT 구조체를 가리키며, 이 구조체는 CERT_TRUST_STATUS 구조체를 가리킵니다. CERT_TRUST_HAS_WEAK_SIGNATURE 값도 약한 서명에 대해 설정됩니다.

요구 사항

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

추가 정보

CertGetCertificateContextProperty

CertSetCertificateContextProperty