CertSelectCertificateChains 函式 (wincrypt.h)

CertSelectCertificateChains 函式會根據指定的選取準則擷取憑證鏈結。

語法

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
);

參數

[in, optional] pSelectionContext

要用於此呼叫之憑證選取案例之 GUID 的指標。

[in] dwFlags

用於控制憑證選取程式的旗標。 此參數可以是下列零個或多個旗標的組合：

值	意義
CERT_SELECT_ALLOW_EXPIRED	選取符合選取準則的過期憑證。 根據預設，已過期的憑證會從選取範圍中拒絕。
CERT_SELECT_TRUSTED_ROOT	選取憑證鏈結信任狀態中的錯誤位未設定為 [CERT_TRUST_IS_UNTRUSTED_ROOT]、 [CERT_TRUST_IS_PARTIAL_CHAIN] 或 [CERT_TRUST_IS_NOT_TIME_VALID]。 此外，未選取具有下列其中一個無效條件約束錯誤的憑證： CERT_TRUST_INVALID_POLICY_CONSTRAINTS CERT_TRUST_INVALID_BASIC_CONSTRAINTS CERT_TRUST_INVALID_NAME_CONSTRAINTS
CERT_SELECT_DISALLOW_SELFSIGNED	選取未自我發行和自我簽署的憑證。
CERT_SELECT_HAS_PRIVATE_KEY	選取已針對憑證 之 CERT_KEY_PROV_INFO_PROP_ID 屬性設定值的憑證。
CERT_SELECT_HAS_KEY_FOR_SIGNATURE	選取CERT_KEY_PROV_INFO_PROP_ID屬性的 dwKeySpec 成員值設定為AT_SIGNATURE的憑證。 如果呼叫此函式做為已啟用 CNG 之應用程式的一部分，且CERT_KEY_PROV_INFO_PROP_ID屬性的 dwKeySpec 成員設定為 -1，請選取相關聯私鑰的 NCRYPT_KEY_USAGE_PROPERTY 屬性值已設定NCRYPT_ALLOW_SIGNING_FLAG的憑證。
CERT_SELECT_HAS_KEY_FOR_KEY_EXCHANGE	選取CERT_KEY_PROV_INFO_PROP_ID屬性的 dwKeySpec 成員值設定為AT_KEYEXCHANGE的憑證。 如果呼叫此函式做為已啟用 CNG 應用程式的一部分，且CERT_KEY_PROV_INFO_PROP_ID屬性的 dwKeySpec 成員設定為 -1，請選取已設定NCRYPT_ALLOW_DECRYPT_FLAG或NCRYPT_ALLOW_KEY_AGREEMENT_FLAG的憑證。
CERT_SELECT_HARDWARE_ONLY	選取相關聯私鑰提供者 之PP_IMPTYPE 屬性值設定為 CRYPT_IMPL_HARDWARE 或 CRYPT_IMPL_REMOVABLE的憑證。 (針對 CNG 提供者，NCRYPT_IMPL_TYPE_PROPERTY屬性值必須具有NCRYPT_IMPL_HARDWARE_FLAG或NCRYPT_IMPL_REMOVABLE_FLAG位集) 。 如果呼叫此函式做為已啟用 CNG 應用程式的一部分，請選取 NCRYPT_IMPL_TYPE_PROPERTY 屬性設定為 NCRYPT_IMPL_HARDWARE_FLAG 或 NCRYPT_IMPL_REMOVABLE_FLAG的憑證。
CERT_SELECT_ALLOW_DUPLICATES	允許選取主體和主體替換名稱包含相同資訊和證書範本延伸模組值相等的憑證。 根據預設，當憑證符合此準則時，只會選取最新的憑證。

[in, optional] pChainParameters

要指定鏈結建置參數 之CERT_SELECT_CHAIN_PARA 結構的指標。 如果 為 NULL，則會使用預設參數。

CERT_SELECT_CHAIN_PARA 結構的 pChainPara 成員會指向可用來啟用強式簽署的CERT_CHAIN_PARA結構。

[in] cCriteria

rgpCriteria 陣列所指向之陣列中的元素數目。

[in, optional] rgpCriteria

定義選取準則之 CERT_SELECT_CRITERIA 結構的陣列指標。 如果此參數設定為 NULL，cCriteria 參數的值必須是零。

[in] hStore

要從中選取憑證之存放區的句柄。

[out] pcSelection

DWORD 值的指標，可接收 pprgpSelection 參數所指向之陣列中的元素數目。

[out] pprgpSelection

要接收 CERT_CHAIN_CONTEXT 結構陣列之位置之指標的指標。 CertSelectCertificateChains 函式只會傳回符合所有選取準則的憑證鏈結。 陣列中的專案會依品質排序，也就是具有最高質量的鏈結是第一個專案。

數位的記憶體是由 CertSelectCertificateChains 函式所配置。 若要釋放配置的記憶體，您必須先呼叫 CertFreeCertificateChain 函式，以釋放數位中的每個個別鏈結內容。 然後，您必須呼叫 CertFreeCertificateChainList 函式來釋放記憶體。

傳回值

如果函式成功，函式會傳回 TRUE。

如果函式失敗，它會傳回零 (FALSE) 。 如需擴充錯誤資訊，請呼叫 GetLastError 函式。

注意 如果選取範圍沒有產生任何結果， CertSelectCertificateChains 函式會傳回 TRUE，但 pcSelection 參數所指向的值會設定為零。

 

備註

選取準則可以透過 dwFlags 參數、 rgpCriteria 參數或兩個參數來指定。 如果未指定選取準則，函式會成功並傳回 hStore 參數所指定之存放區中所有憑證的憑證鏈結。

選取的憑證鏈結會根據下列喜好設定邏輯排序：

• 偏好使用智慧卡憑證的憑證，而非智慧卡型憑證。
• 偏好具有較長有效期限的憑證， (到期日較晚。)
• 如果多個憑證具有相同的到期日，偏好最近發行的憑證。
• 如果有系結，偏好較短的鏈結。

特定選取準則需要建立憑證鏈結，才能選取該準則以供使用。 如果建置鏈結所需的中繼憑證無法在本機使用，則會針對簽發者憑證執行網路擷取。 如果 已設定 CERT_SELECT_TRUSTED_ROOT 旗標或下列準則，就會執行此網路擷取：

• CERT_SELECT_BY_ISSUER_NAME
• CERT_SELECT_BY_ISSUER_ATTR
• CERT_SELECT_BY_POLICY_OID

執行下列動作以啟用強式簽章檢查：

• 建立CERT_STRONG_SIGN_PARA結構、指定必要的強式簽署參數，並在 CERT_CHAIN_PARA 結構的 pStrongSignPara 成員中設定結構的指標。
• 在 CERT_SELECT_CHAIN_PARA 結構的 pChainPara 成員中，設定CERT_CHAIN_PARA結構的指標。
• 在此 (CertSelectCertificateChain) s 函式的 pChainParameters 參數中，設定CERT_SELECT_CHAIN_PARA結構的指標。

當您啟用強式簽章檢查時，將會略過在 CERT_TRUST_STATUS 結構的 dwErrorStatus 字段中傳回CERT_TRUST_IS_NOT_SIGNATURE_VALID錯誤的任何憑證鏈結。 (pprgpSelection 參數會指向 CERT_CHAIN_CONTEXT 結構，接著指向 CERT_TRUST_STATUS structure.) 也會針對弱式簽章設定 CERT_TRUST_HAS_WEAK_SIGNATURE 值。

規格需求

需求	值
最低支援的用戶端	Windows 7 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器	Windows Server 2008 R2 [傳統型應用程式 |UWP 應用程式]
目標平台	Windows
標頭	wincrypt.h
程式庫	Crypt32.lib
Dll	Crypt32.dll

另請參閱

CertGetCertificateContextProperty

CertSetCertificateContextProperty