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

証明書の選択プロセスを制御するためのフラグ。 このパラメーターには、次のフラグの 0 個以上の組み合わせを指定できます。

値 意味
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 パラメーターの値は 0 である必要があります。

[in] hStore

証明書の選択元となるストアへのハンドル。

[out] pcSelection

pprgpSelection パラメーターが指す配列内の要素の数を受け取る DWORD 値へのポインター。

[out] pprgpSelection

構造体の配列を受け取る場所へのポインター CERT_CHAIN_CONTEXT ポインター。 CertSelectCertificateChains 関数は、すべての選択条件に一致する証明書チェーンのみを返します。 配列内のエントリは品質順に並べ替えられます。つまり、最も品質の高いチェーンが最初のエントリです。

配列のストレージは、 CertSelectCertificateChains 関数によって割り当てられます。 割り当てられたメモリを解放するには、 まず CertFreeCertificateChain 関数を呼び出して、配列内の各チェーン コンテキストを解放する必要があります。 その後、 CertFreeCertificateChainList 関数を呼び出してメモリを解放する必要があります。

戻り値

関数が成功した場合、関数は TRUE を返します。

関数が失敗した場合は、0 (FALSE) を返します。 拡張エラー情報については、 GetLastError 関数を呼び出します。

メモ 選択しても結果が得られない場合、 CertSelectCertificateChains 関数は TRUE を返しますが、 pcSelection パラメーターが指す値は 0 に設定されます。
 

注釈

選択条件は、 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構造体へのポインターを設定します。
  • この (CertSelectCertificateChains) 関数の pChainParameters パラメーターで、CERT_SELECT_CHAIN_PARA構造体へのポインターを設定します。

厳密な署名チェックを有効にすると、CERT_TRUST_STATUS構造体の dwErrorStatus フィールドでCERT_TRUST_IS_NOT_SIGNATURE_VALID エラーを返す証明書チェーンはスキップされます。 ( pprgpSelection パラメーターは 、CERT_CHAIN_CONTEXT 構造体を指し、 CERT_TRUST_STATUS構造体を 指します)。 CERT_TRUST_HAS_WEAK_SIGNATURE 値は、弱いシグネチャにも設定されます。

要件

要件 値
サポートされている最小のクライアント Windows 7 [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 R2 [デスクトップ アプリ |UWP アプリ]
対象プラットフォーム Windows
ヘッダー wincrypt.h
Library Crypt32.lib
[DLL] Crypt32.dll

こちらもご覧ください

CertGetCertificateContextProperty

CertSetCertificateContextProperty