CertGetCertificateChain 関数 (wincrypt.h)

CertGetCertificateChain 関数は、証明書チェーン コンテキストをエンド証明書から開始し、可能であれば、信頼された ルート証明書に戻ります。

構文

BOOL CertGetCertificateChain(
  [in, optional] HCERTCHAINENGINE     hChainEngine,
  [in]           PCCERT_CONTEXT       pCertContext,
  [in, optional] LPFILETIME           pTime,
  [in]           HCERTSTORE           hAdditionalStore,
  [in]           PCERT_CHAIN_PARA     pChainPara,
  [in]           DWORD                dwFlags,
  [in]           LPVOID               pvReserved,
  [out]          PCCERT_CHAIN_CONTEXT *ppChainContext
);

パラメーター

[in, optional] hChainEngine

使用するチェーン エンジン (名前空間とキャッシュ) のハンドル。 hChainEngine が NULLされている場合は、既定のチェーン エンジンである HCCE_CURRENT_USERが使用されます。 このパラメーターは、HCCE_LOCAL_MACHINEに設定できます。

[in] pCertContext

エンド証明書の CERT_CONTEXT へのポインター。チェーンが構築されている証明書。 この証明書コンテキストは、最初の単純チェーンの 0 インデックス要素になります。

[in, optional] pTime

チェーンを検証する時刻を示す FILETIME 変数へのポインター。 時間は信頼リスト、失効、またはルート ストアのチェックには影響しないことに注意してください。 現在のシステム時刻は、NULL がこのパラメーターに渡される場合に使用されます。 信頼されたルートである特定の証明書の信頼は、ルート ストアの現在の 状態 に基づいており、このパラメーターで渡された時点でのルート ストアの状態には基づいていません。 失効の場合、証明書失効リスト (CRL) 自体が現在有効である必要があります。 このパラメーターの値は、CRL にリストされている証明書が取り消されたかどうかを判断するために使用されます。

[in] hAdditionalStore

サポート証明書と証明書信頼リスト (CCTL) を 検索する追加ストアへのハンドル。 追加のストアを検索しない場合は、このパラメーターを NULL できます。

[in] pChainPara

チェーン構築パラメーターを含む CERT_CHAIN_PARA 構造体へのポインター。

[in] dwFlags

特別な処理を示す値にフラグを設定します。 このパラメーターには、次のフラグの 1 つ以上を組み合わせて使用できます。

次の失効フラグを設定することもできますが、このグループのフラグは一度に 1 つだけ設定できます。

[in] pvReserved

このパラメーターは予約されており、NULLする必要があります。

[out] ppChainContext

作成されたチェーン コンテキストへのポインターのアドレス。 チェーン コンテキストの使用が完了したら、CertFreeCertificateChain 関数を呼び出してチェーンを解放します。

戻り値

関数が成功した場合、関数は 0 以外 (TRUE) を返します。

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

備考

アプリケーションが証明書チェーンを要求すると、返される構造体は CERT_CHAIN_CONTEXTの形式になります。 このコンテキストには、各単純なチェーンがエンド証明書から自己署名証明書に送信される CERT_SIMPLE_CHAIN 構造の配列が含まれています。 チェーン コンテキストは、信頼リストを介して単純なチェーンを接続します。 各単純チェーンには、証明書のチェーン、チェーンに関する要約信頼情報、およびチェーン内の各証明書要素に関する信頼情報が含まれています。

厳密な署名チェックには、次の注釈が適用されます。

• この関数に対して厳密な署名チェックを有効にするには、pChainPara パラメーターが指す CERT_CHAIN_PARA 構造体の pStrongSignPara メンバーを設定します。
• チェーンに厳密な署名のない証明書が見つかった場合、CERT_TRUST_HAS_WEAK_SIGNATURE と CERT_TRUST_IS_NOT_SIGNATURE_VALID のエラーは、CERT_TRUST_STATUS 構造体の dwErrorStatus フィールドに設定されます。 ppChainContext パラメーターは、CERT_TRUST_STATUS 構造体を指す CERT_CHAIN_CONTEXT 構造体を指します。
• チェーンが厳密に署名されている場合は、エンド証明書の公開キーがチェックされ、厳密な署名の最小公開キーの長さの要件を満たしているかどうかを判断します。 条件が満たされていない場合、CERT_TRUST_STATUS 構造体の dwErrorStatus フィールドに CERT_TRUST_HAS_WEAK_SIGNATURE エラーと CERT_TRUST_IS_NOT_SIGNATURE_VALID エラーが設定されます。 キーの長さのチェックを無効にするには、pChainPara パラメーターが指す CERT_CHAIN_PARA 構造体の dwStrongSignFlags メンバーに CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG 値を設定します。
• CERT_STRONG_SIGN_ENABLE_CRL_CHECK または CERT_STRONG_SIGN_ENABLE_OCSP_CHECK フラグが CERT_STRONG_SIGN_SERIALIZED_INFO 構造で設定されていて、CRL または OCSP 応答が厳密な署名なしで見つかった場合、CRL または OCSP 応答はオフラインとして扱われます。 つまり、CERT_TRUST_IS_OFFLINE_REVOCATION エラーと CERT_TRUST_REVOCATION_STATUS_UNKNOWN エラーは、CERT_TRUST_STATUS 構造体の dwErrorStatus フィールドに設定されます。 また、CERT_REVOCATION_INFO 構造体の dwRevocationResult メンバーは、NTE_BAD_ALGIDに設定されます。

次の推奨事項は、これらの API を呼び出して TLS サーバー認証証明書を確認する Windows アプリケーションに適用されます。

• 終了証明書の失効チェックのみを有効にします。
  • フラグ CERT_CHAIN_REVOCATION_CHECK_END_CERT 設定します。
  • ほとんどの CA 証明書には CRL があり、有効期間は 1 ~ 6 か月です。
    • ダウンロードされた CRL はキャッシュされるため、この有効性は長すぎて多くの値を持つことになります。
  • CA 侵害がある場合、証明書は Windows 許可されていない CTL にも追加されます。
  • TLS サーバーの推奨される方法は、エンド証明書の OCSP ステープリングをサポートすることです。
    • その場合、ホチキス止めされた OCSP 応答の有効期限が切れていない限り、ネットワーク取得は必要ありません。
• CRL、OCSP、AIA 発行者、Windows プラットフォーム CTL cab、サード パーティルートのネットワーク取得を有効にします。
  • 上記の CERT_CHAIN_REVOCATION_CHECK_END_CERT が設定されている場合は、これが既定値です。
  • ネットワークの取得を防ぐために、次のフラグを設定しないでください。 これらのフラグの詳細については、上記の dwFlags 表を参照してください。
    • CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
    • CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
    • CERT_CHAIN_DISABLE_AIA
• CRL および OCSP ネットワーク取得の累積タイムアウトを有効にします。
  • CertGetCertificateChainに渡される CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT フラグを設定します。
  • CRL および OCSP ネットワークの取得に許可される合計時間の上限を提供します。
• 各ネットワーク取得に許容される最大時間を 15 秒から 10 秒に短縮します。
  • CertGetCertificateChain に渡された CERT_CHAIN_PARA の dwUrlRetrievalTimeout フィールドを 10 * 1000 ミリ秒に設定します。
  • これにより、累積タイムアウトが 20 秒から 10 秒に短縮されます。
    • エンド証明書には OCSP 応答のみをダウンロードする必要があります。 そのダウンロードには 5 秒で十分です。
• オフライン失効エラーを無視します。
  • CertVerifyCertificateChainPolicy(CERT_CHAIN_POLICY_SSL)に渡される CERT_CHAIN_POLICY_PARA の CERT_CHAIN_POLICY_IGNORE_ALL_REV_UNKNOWN_FLAGS を設定します。
  • OCSP と CRL のネットワーク取得が最適です。 ほとんどのネットワーク取得は数秒で成功するはずですが、100% 保証されません。
• 証明書の検証情報をキャッシュします。
  • CERT_CHAIN_CACHE_END_CERTを設定します。
    • 中間証明書に加えて、エンド証明書に関する情報の LRU キャッシュを有効にします。
  • 同じサーバーに対して複数の TLS 接続を行うのが一般的です。

例

この関数を使用する例については、「例 C プログラム: 証明書チェーンの作成」を参照してください。

必要条件

関連項目

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

証明書チェーン検証機能