Edit

Share via

CertSelectCertificateChains function (wincrypt.h)

  • Article

The CertSelectCertificateChains function retrieves certificate chains based on specified selection criteria.

Syntax

BOOL CertSelectCertificateChains(
  [in, optional] LPCGUID                  pSelectionContext,
  [in]           DWORD                    dwFlags,
  [in, optional] PCCERT_SELECT_CHAIN_PARA pChainParameters,
  [in]           DWORD                    cCriteria,
  [in, optional] PCCERT_SELECT_CRITERIA   rgpCriteria,
  [in]           HCERTSTORE               hStore,
  [out]          PDWORD                   pcSelection,
  [out]          PCCERT_CHAIN_CONTEXT     **pprgpSelection
);

Parameters

[in, optional] pSelectionContext

A pointer to the GUID of the certificate selection scenario to use for this call.

[in] dwFlags

Flags for controlling the certificate selection process. This parameter can be a combination of zero or more of the following flags:

Value Meaning
CERT_SELECT_ALLOW_EXPIRED
 Select expired certificates that meet selection criteria. By default expired certificates are rejected from selection.
CERT_SELECT_TRUSTED_ROOT
 Select certificates on which the error bit in the certificate chain trust status is not set to CERT_TRUST_IS_UNTRUSTED_ROOT, CERT_TRUST_IS_PARTIAL_CHAIN, or CERT_TRUST_IS_NOT_TIME_VALID.

In addition, certificates that have one of the following invalid constraint errors are not selected:

  • CERT_TRUST_INVALID_POLICY_CONSTRAINTS
  • CERT_TRUST_INVALID_BASIC_CONSTRAINTS
  • CERT_TRUST_INVALID_NAME_CONSTRAINTS
CERT_SELECT_DISALLOW_SELFSIGNED
 Select certificates that are not self-issued and self-signed.
CERT_SELECT_HAS_PRIVATE_KEY
 Select certificates that have a value set for the CERT_KEY_PROV_INFO_PROP_ID property of the certificate.
CERT_SELECT_HAS_KEY_FOR_SIGNATURE
 Select certificates on which the value of the dwKeySpec member of the CERT_KEY_PROV_INFO_PROP_ID property is set to AT_SIGNATURE.

If this function is being called as part of a CNG enabled application and the dwKeySpec member of the CERT_KEY_PROV_INFO_PROP_ID property is set to -1, select certificates on which the value of the NCRYPT_KEY_USAGE_PROPERTY property of the associated private key has the NCRYPT_ALLOW_SIGNING_FLAG set.
CERT_SELECT_HAS_KEY_FOR_KEY_EXCHANGE
 Select certificates on which the value of the dwKeySpec member of the CERT_KEY_PROV_INFO_PROP_ID property is set to AT_KEYEXCHANGE.

If this function is being called as part of a CNG enabled application and the dwKeySpec member of the CERT_KEY_PROV_INFO_PROP_ID property is set to -1, select certificates on which either NCRYPT_ALLOW_DECRYPT_FLAG or NCRYPT_ALLOW_KEY_AGREEMENT_FLAG is set.
CERT_SELECT_HARDWARE_ONLY
 Select certificates on which the value of the PP_IMPTYPE property of the associated private key provider is set to either CRYPT_IMPL_HARDWARE or CRYPT_IMPL_REMOVABLE. (For CNG providers, NCRYPT_IMPL_TYPE_PROPERTY property value MUST have either the NCRYPT_IMPL_HARDWARE_FLAG or NCRYPT_IMPL_REMOVABLE_FLAG bit set).

If this function is being called as part of a CNG enabled application, select certificates on which the NCRYPT_IMPL_TYPE_PROPERTY property is set to NCRYPT_IMPL_HARDWARE_FLAG or NCRYPT_IMPL_REMOVABLE_FLAG.
CERT_SELECT_ALLOW_DUPLICATES
 Allow the selection of certificates on which the Subject and Subject Alt Name contain the same information and the certificate template extension value is equivalent. By default when certificates match this criteria, only the most recent certificate is selected.

[in, optional] pChainParameters

A pointer to a CERT_SELECT_CHAIN_PARA structure to specify parameters for chain building. If NULL, default parameters will be used.

The pChainPara member of the CERT_SELECT_CHAIN_PARA structure points to a CERT_CHAIN_PARA structure that can be used to enable strong signing.

[in] cCriteria

The number of elements in the array pointed to by the rgpCriteria array.

[in, optional] rgpCriteria

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.

[in] hStore

The handle to a store from which to select the certificates.

[out] pcSelection

A pointer to a DWORD value to receive the number of elements in the array pointed to by the pprgpSelection parameter.

[out] pprgpSelection

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.

Return value

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.
 

Remarks

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:
  • CERT_SELECT_BY_ISSUER_NAME
  • CERT_SELECT_BY_ISSUER_ATTR
  • CERT_SELECT_BY_POLICY_OID
Perform the following actions to enable strong signature checking:

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.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps | UWP apps]
Minimum supported server Windows Server 2008 R2 [desktop apps | UWP apps]
Target Platform Windows
Header wincrypt.h
Library Crypt32.lib
DLL Crypt32.dll

See also

CertGetCertificateContextProperty

CertSetCertificateContextProperty