CertGetCertificateChain

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 of the chain engine (name space and cache) to be used. If the hChainEngine value 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 zero index element 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 of any additional store to searched 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 following table shows the flag that can be used.

    Flag Description
    CERT_CHAIN_CACHE_END_CERT 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] A reserved parameter that must be NULL.

  • ppChainContext
    [in] Pointer to a pointer to the chain context created.

Return Values

If the function succeeds, the return value is nonzero (TRUE).

If the function fails, the return value is zero (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 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, but Windows CE does not:

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

Runs on Versions Defined in Include Link to
Windows CE OS 3.0 or later Wincrypt.h   Crypt32.lib

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

CertFreeCertificateChain, CertDuplicateCertificateChain, CERT_CHAIN_CONTEXT, CERT_CHAIN_PARA, CERT_CONTEXT, CERT_SIMPLE_CHAIN

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.