CertGetCertificateChain Function (Windows)

CertGetCertificateChain Function

CertGetCertificateChain Function

The CertGetCertificateChain function builds a certificate chain context starting from an end certificate and going back, if possible, to a trusted root certificate.

Syntax

C++

BOOL WINAPI CertGetCertificateChain(
  __in_opt  HCERTCHAINENGINE hChainEngine,
  __in      PCCERT_CONTEXT pCertContext,
  __in_opt  LPFILETIME pTime,
  __in      HCERTSTORE hAdditionalStore,
  __in      PCERT_CHAIN_PARA pChainPara,
  __in      DWORD dwFlags,
  __in      LPVOID pvReserved,
  __out     PCCERT_CHAIN_CONTEXT *ppChainContext
);

Parameters

hChainEngine [in, optional]

A handle of the chain engine (namespace and cache) to be used. If hChainEngine is NULL, the default chain engine, HCCE_CURRENT_USER, is used. This parameter can be set to HCCE_LOCAL_MACHINE.

pCertContext [in]

A pointer to the CERT_CONTEXT of the end certificate, the certificate for which a chain is being built. This certificate context will be the zero-index element in the first simple chain.

pTime [in, optional]

A pointer to a FILETIME variable that indicates the time for which the chain is to be validated. Note that the time does not affect trust list, revocation, or root store checking. The current system time is used if NULL is passed to this parameter. Trust in a particular certificate being a trusted root is based on the current state of the root store and not the state of the root store at a time passed in by this parameter. For revocation, a certificate revocation list (CRL), itself, must be valid at the current time. The value of this parameter is used to determine whether a certificate listed in a CRL has been revoked.

hAdditionalStore [in]

A handle to any additional store to search for supporting certificates and certificate trust lists (CTLs). This parameter can be NULL if no additional store is to be searched.

pChainPara [in]

A pointer to a CERT_CHAIN_PARA structure that includes chain-building parameters.

dwFlags [in]

Flag values that indicate special processing. This parameter can be a combination of one or more of the following flags.

Value	Meaning
CERT_CHAIN_REVOCATION_CHECK_END_CERT 0x10000000	Revocation checking is done on the end certificate and only the end certificate.
CERT_CHAIN_REVOCATION_CHECK_CHAIN 0x20000000	Revocation checking is done on all of the certificates in every chain.
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT 0x40000000	Revocation checking is done on all certificates in all of the chains except the root certificate.
CERT_CHAIN_CACHE_END_CERT 0x00000001	When this flag is set, the end certificate is cached, which might speed up the chain-building process. By default, the end certificate is not cached, and it would need to be verified each time a chain is built for it.
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY 0x80000000	Revocation checking only accesses cached URLs.
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT 0x04000000	Revocation checking is done for an independent online certificate status protocol (OCSP) signer certificate. This flag is used to inhibit recursive independent OCSP signer certificates. If the signer certificate contains the szOID_PKIX_OCSP_NOCHECK extension, revocation checking is skipped for the leaf signer certificate. Both OCSP and CRL checking are allowed. Windows Server 2003, Windows XP, and Windows 2000: This value is not supported.
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL 0x00000004	Uses only cached URLs in building a certificate chain. The Internet and intranet are not searched for URL-based objects. Note This flag is not applicable to revocation checking. Set CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY to use only cached URLs for revocation checking.
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING 0x00000040	For performance reasons, the second pass of chain building only considers potential chain paths that have quality greater than or equal to the highest quality determined during the first pass. The first pass only considers valid signature, complete chain, and trusted roots to calculate chain quality. This flag can be set to disable this optimization and consider all potential chain paths during the second pass.
CERT_CHAIN_DISABLE_MY_PEER_TRUST 0x00000800	This flag is not supported. Certificates in the "My" store are never considered for peer trust.
CERT_CHAIN_ENABLE_PEER_TRUST 0x00000400	End entity certificates in the "TrustedPeople" store are trusted without performing any chain building. This function does not set the CERT_TRUST_IS_PARTIAL_CHAIN or CERT_TRUST_IS_UNTRUSTED_ROOT dwErrorStatus member bits of the ppChainContext parameter. Windows Server 2003, Windows XP, and Windows 2000: This flag is not supported.
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS 0x00000080	The default is to return only the highest quality chain path. Setting this flag will return the lower quality chains. These are returned in the cLowerQualityChainContext and rgpLowerQualityChainContext fields of the chain context.
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE 0x00000100	Setting this flag inhibits the auto update of third-party roots from the Windows Update Web Server.
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT 0x08000000	When CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT is specified, dwUrlRetrievalTimeout is the cumulative time-out across all revocation URL wire retrievals.
CERT_CHAIN_TIMESTAMP_TIME 0x00000200	When this flag is set, pTime is used as the time stamp time to determine whether the end certificate was time valid. Current time can also be used to determine whether the end certificate remains time valid. All other certification authority (CA) and root certificates in the chain are checked by using current time and not pTime.

pvReserved [in]

This parameter is reserved and must be NULL.

ppChainContext [out]

The address of a pointer to the chain context created. When you have finished using the chain context, release the chain by calling the CertFreeCertificateChain function.

Return Value

If the function succeeds, the function returns nonzero (TRUE).

If the function fails, it returns zero (FALSE). For extended error information, call GetLastError.

Remarks

When an application requests a certificate chain, the structure returned is in the form of a CERT_CHAIN_CONTEXT. This context contains an array of CERT_SIMPLE_CHAIN structures where each simple chain goes from an end certificate to a self-signed certificate. The chain context connects simple chains through trust lists. Each simple chain contains the chain of certificates, summary trust information about the chain, and trust information about each certificate element in the chain.

Examples

For an example that uses this function, see Example C Program: Creating a Certificate Chain.

Requirements