CertGetCertificateChain

  • Article

This function builds a certificate chain context starting from an end certificate and going back, if possible, to a trusted root certificate. This is the primary API used to verify a certificate against a root store.

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

Parameters

  • hChainEngine
    [in] Optional. Handle to the chain engine, which includes name space and cache, to be used. If the value of this parameter is NULL, the default chain engine, HHCE_CURRENT_USER, is used. This parameter can be set to HCCE_LOCAL_MACHINE.
  • pCertContext
    [in] Pointer to the CERT_CONTEXT structure of the end certificate, the certificate for which a chain is being built. This certificate context will be the element with zero index in the first simple chain.
  • pTime
    [in] Optional. Pointer to a FILETIME variable indicating the time for which the chain is to be validated. Note that the time does not affect 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.
  • hAdditionalStore
    [in] Handle to any additional store to search for supporting certificates. This parameter can be NULL if no additional store is to be searched.
  • pChainPara
    [in] Pointer to a CERT_CHAIN_PARA structure that includes chain-building parameters.
  • dwFlags
    [in] Flag values indicating special processing. The CERT_CHAIN_CACHE_END_CERT flag can be used. 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.
  • pvReserved
    [in] Reserved parameter that must be set to NULL.
  • ppChainContext
    [in] Pointer to a pointer to the chain context created.

Return Values

If the function succeeds, the return value is nonzero, or TRUE.

If the function fails, the return value is zero, or FALSE. For extended error information, call the GetLastError function.

Remarks

When an application requests a certificate chain, the structure returned is in the form of a CERT_CHAIN_CONTEXT structure. This context contains an array of CERT_SIMPLE_CHAIN structures where each simple chain goes from an end certificate to a self-signed certificate. Because Windows CE does not support certificate trust lists, there is only one CERT_SIMPLE_CHAIN in the array. Each simple chain contains the chain of certificates, summary trust information about the chain, and trust information about each certificate element in the chain.

The desktop platform supports the following dwFlags flags that Windows CE does not support:

CERT_CHAIN_REVOCATION_CHECK_END_CERT

CERT_CHAIN_REVOCATION_CHECK_CHAIN

CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT

CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY.

Requirements

OS Versions: Windows CE 3.0 and later.
Header: Wincrypt.h.
Link Library: Crypt32.lib.

See Also

CertFreeCertificateChain | CertDuplicateCertificateChain | CERT_CHAIN_CONTEXT | CERT_CHAIN_PARA | CERT_CONTEXT | CERT_SIMPLE_CHAIN

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.