The CertSelectCertificateChains function retrieves certificate chains based on specified selection criteria.
BOOL WINAPI CertSelectCertificateChains( _In_opt_ LPCGUID pSelectionContext, _In_ DWORD dwFlags, _In_opt_ PCCERT_SELECT_CHAIN_PARA pChainParameters, _In_ DWORD cCriteria, _In_opt_ PCCERT_SELECT_CRITERIA rgpCriteria, _In_ HCERTSTORE hStore, _Out_ PDWORD pcSelection, _Out_ PCCERT_CHAIN_CONTEXT **pprgpSelection );
- pSelectionContext [in, optional]
A pointer to the GUID of the certificate selection scenario to use for this call.
- dwFlags [in]
Flags for controlling the certificate selection process. This parameter can be a combination of zero or more of the following flags:
- pChainParameters [in, optional]
A pointer to a CERT_SELECT_CHAIN_PARA structure to specify parameters for chain building. If NULL, default parameters will be used.
- cCriteria [in]
The number of elements in the array pointed to by the rgpCriteria array.
- rgpCriteria [in, optional]
A pointer to an array of CERT_SELECT_CRITERIA structures that define the selection criteria. If this parameter is set to NULL, the value of the cCriteria parameter must be zero.
- hStore [in]
The handle to a store from which to select the certificates.
- pcSelection [out]
A pointer to a DWORD value to receive the number of elements in the array pointed to by the pprgpSelection parameter.
- pprgpSelection [out]
A pointer to a pointer to a location to receive an array of CERT_CHAIN_CONTEXT structure. The CertSelectCertificateChains function only returns certificate chains that match all the selection criteria. The entries in the array are ordered by quality, i.e. the chain with the highest quality is the first entry.
Storage for the array is allocated by the CertSelectCertificateChains function. To free the allocated memory you must first release each individual chain context in the array by calling the CertFreeCertificateChain function. Then you must free the memory by calling the CertFreeCertificateChainList function.
If the function succeeds, the function returns TRUE.
If the function fails, it returns zero (FALSE). For extended error information, call the GetLastError function.
Note If the selection does not yield any results, the CertSelectCertificateChains function returns TRUE, but the value pointed to by pcSelection parameter is set to zero.
Selection criteria can be specified through either the dwFlags parameter, through the rgpCriteria parameter, or through both parameters. If no selection criteria are specified, the function succeeds and returns certificate chains for all certificates in the store specified by the hStore parameter.
Certificate chains that are selected are ordered based on the following preference logic:
- Prefer certificates that are smart card certificates over certificates that are not smart-card based.
- Prefer certificates that have a longer validity period (the expiration date is later.)
- If multiple certificates have same expiration date, prefer certificates that were issued more recently.
- If there is a tie, prefer shorter chains.
Certain selection criteria require that a certificate chain be built before you can select that criteria for use. If the intermediate certificates required to build the chain are not available locally, a network retrieval is performed for the issuer certificates. This network retrieval is performed if the CERT_SELECT_TRUSTED_ROOT flag is set or for the following criteria:
Perform the following actions to enable strong signature checking:
- Create a CERT_STRONG_SIGN_PARA structure, specify the required strong signing parameters, and set a pointer to the structure in the pStrongSignPara member of a CERT_CHAIN_PARA structure.
- Set a pointer to the CERT_CHAIN_PARA structure in the pChainPara member of a CERT_SELECT_CHAIN_PARA structure.
- Set a pointer to the CERT_SELECT_CHAIN_PARA structure in the pChainParameters parameter of this (CertSelectCertificateChains)function.
When you enable strong signature checking, any certificate chain that returns a CERT_TRUST_IS_NOT_SIGNATURE_VALID error in the dwErrorStatus field of the CERT_TRUST_STATUS structure will be skipped. (The pprgpSelection parameter points to a CERT_CHAIN_CONTEXT structure which, in turn, points to the CERT_TRUST_STATUS structure.) The CERT_TRUST_HAS_WEAK_SIGNATURE value is also set for a weak signature.
Minimum supported client
|Windows 7 [desktop apps only]|
Minimum supported server
|Windows Server 2008 R2 [desktop apps only]|