EN
Este contenido no se encuentra disponible en su idioma, pero aquí tiene la versión en inglés.

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


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.

ValueMeaning
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

This flag is used internally during chain building for an online certificate status protocol (OCSP) signer certificate to prevent cyclic revocation checks. During chain building, if the OCSP response is signed by an independent OCSP signer, then, in addition to the original chain build, there is a second chain built for the OCSP signer certificate itself. This flag is used during this second chain build to inhibit a recursive independent OCSP signer certificate. 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 and Windows XP:  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 and Windows XP:  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 you set CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT and you also specify a value for the dwUrlRetrievalTimeout member of the CERT_CHAIN_PARA structure, the value you specify in dwUrlRetrievalTimeout represents the cumulative timeout across all revocation URL retrievals.

If you set CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT but do not specify a dwUrlRetrievalTimeout value, the maximum cumulative timeout is set, by default, to 20 seconds. Each URL tested will timeout after half of the remaining cumulative balance has passed. That is, the first URL times out after 10 seconds, the second after 5 seconds, the third after 2.5 seconds and so on until a URL succeeds, 20 seconds has passed, or there are no more URLs to test.

If you do not set CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT, each revocation URL in the chain is assigned a maximum timeout equal to the value specified in dwUrlRetrievalTimeout. If you do not specify a value for the dwUrlRetrievalTimeout member, each revocation URL is assigned a maximum default timeout of 15 seconds. If no URL succeeds, the maximum cumulative timeout value is 15 seconds multiplied by the number of URLs in the chain.

You can set the default values by using Group Policy.

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.

 

You can also set the following revocation flags, but only one flag from this group may be set at a time.

ValueMeaning
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.

 

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.

The following remarks apply to strong signature checking:

  • You can enable strong signature checking for this function by setting the pStrongSignPara member of the CERT_CHAIN_PARA structure that is pointed to by the pChainPara parameter.

  • If a certificate without a strong signature is found in the chain, the CERT_TRUST_HAS_WEAK_SIGNATURE and CERT_TRUST_IS_NOT_SIGNATURE_VALID errors are set in the dwErrorStatus field of the CERT_TRUST_STATUS structure. The ppChainContext parameter points to a CERT_CHAIN_CONTEXT structure which, in turn, points to the CERT_TRUST_STATUS structure.

  • If the chain is strong signed, the public key in the end certificate is checked to determine whether it satisfies the minimum public key length requirements for a strong signature. If the condition is not satisfied, the CERT_TRUST_HAS_WEAK_SIGNATURE and CERT_TRUST_IS_NOT_SIGNATURE_VALID errors are set in the dwErrorStatus field of the CERT_TRUST_STATUS structure. To disable checking the key length, set the CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG value in the dwStrongSignFlags member of the CERT_CHAIN_PARA structure pointed to by the pChainPara parameter.

  • If the CERT_STRONG_SIGN_ENABLE_CRL_CHECK or CERT_STRONG_SIGN_ENABLE_OCSP_CHECK flags are set in the CERT_STRONG_SIGN_SERIALIZED_INFO structure and a CRL or OCSP response is found without a strong signature, the CRL or OCSP response will be treated as being offline. That is, the CERT_TRUST_IS_OFFLINE_REVOCATION and CERT_TRUST_REVOCATION_STATUS_UNKNOWN errors are set in the dwErrorStatus field of the CERT_TRUST_STATUS structure. Also, the dwRevocationResult member of the CERT_REVOCATION_INFO structure is set to NTE_BAD_ALGID.

Examples

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

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Crypt32.lib

DLL

Crypt32.dll

See also

Certificate Chain Verification Functions
CERT_CHAIN_PARA
CertFreeCertificateChain
CertDuplicateCertificateChain

 

 

Adiciones de comunidad

AGREGAR
Mostrar:
© 2014 Microsoft. Reservados todos los derechos.