The CertSelectCertificateChains function retrieves certificate chains based on specified selection criteria.
BOOL CertSelectCertificateChains( LPCGUID pSelectionContext, DWORD dwFlags, PCCERT_SELECT_CHAIN_PARA pChainParameters, DWORD cCriteria, PCCERT_SELECT_CRITERIA rgpCriteria, HCERTSTORE hStore, PDWORD pcSelection, PCCERT_CHAIN_CONTEXT **pprgpSelection );
A pointer to the GUID of the certificate selection scenario to use for this call.
Flags for controlling the certificate selection process. This parameter can be a combination of zero or more of the following flags:
A pointer to a CERT_SELECT_CHAIN_PARA structure to specify parameters for chain building. If NULL, default parameters will be used.
The number of elements in the array pointed to by the rgpCriteria array.
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.
The handle to a store from which to select the certificates.
A pointer to a DWORD value to receive the number of elements in the array pointed to by the pprgpSelection parameter.
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.
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.
- 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 | UWP apps]|
|Minimum supported server||Windows Server 2008 R2 [desktop apps | UWP apps]|