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-index 要素になります。

[in, optional] pTime

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

[in] hAdditionalStore

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

[in] pChainPara

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

[in] dwFlags

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

値 説明
CERT_CHAIN_CACHE_END_CERT
0x00000001
 このフラグを設定すると、終了証明書がキャッシュされるため、チェーン構築プロセスが高速化される可能性があります。 既定では、終了証明書はキャッシュされないため、チェーンが構築されるたびに検証する必要があります。
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
0x80000000
 失効チェックは、キャッシュされた URL にのみアクセスします。
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT
0x04000000
 このフラグは、循環失効チェックを防ぐために、 オンライン証明書状態プロトコル (OCSP) 署名者証明書のチェーン構築中に内部的に使用されます。 チェーンの構築中に、OCSP 応答が独立した OCSP 署名者によって署名された場合、元のチェーン ビルドに加えて、OCSP 署名者証明書自体用に構築された 2 つ目のチェーンがあります。 このフラグは、再帰的に独立した OCSP 署名者証明書を禁止するために、この 2 番目のチェーンビルド中に使用されます。 署名者証明書に szOID_PKIX_OCSP_NOCHECK 拡張機能が含まれている場合、リーフ署名者証明書の失効チェックはスキップされます。 OCSP と CRL の両方のチェックが許可されます。

Windows Server 2003 および Windows XP: この値はサポートされていません。
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
0x00000004
 証明書チェーンの構築でキャッシュされた URL のみを使用します。 インターネットとイントラネットでは、URL ベースのオブジェクトは検索されません。

メモ このフラグは失効チェックには適用されません。 失効チェックにキャッシュされた URL のみを使用するようにCERT_CHAIN_REVOCATION_CHECK_CACHE_ONLYを設定します。
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING
0x00000040
 パフォーマンス上の理由から、チェーン構築の 2 番目のパスでは、最初のパスで決定された最高の品質以上の品質を持つ潜在的なチェーン パスのみが考慮されます。 最初のパスでは、チェーンの品質を計算するために、有効な署名、完全なチェーン、信頼されたルートのみが考慮されます。 このフラグを設定すると、この最適化を無効にし、2 回目のパス中にチェーン パスが発生する可能性があるすべてのパスを考慮できます。
CERT_CHAIN_DISABLE_MY_PEER_TRUST
0x00000800
 このフラグはサポートされていません。 "My" ストア内の証明書は、ピア信頼とは見なされません。
CERT_CHAIN_ENABLE_PEER_TRUST
0x00000400
 "TrustedPeople" ストア内のエンド エンティティ証明書は、チェーン構築を実行せずに信頼されます。 この関数は、ppChainContext パラメーターのCERT_TRUST_IS_PARTIAL_CHAINまたは dwErrorStatus メンバー ビットCERT_TRUST_IS_UNTRUSTED_ROOT設定しません。 Windows Server 2003 Windows XP: このフラグはサポートされていません。
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE
0x00010000
 このフラグを設定すると、呼び出し元が弱い署名チェックをオプトインすることを望んでいることを示します。

このフラグは、Windows 7 および Windows Server 2008 R2 以降の各 OS のロールアップ更新プログラムで使用できます。
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS
0x00000080
 既定では、最高品質のチェーン パスのみが返されます。 このフラグを設定すると、品質の低いチェーンが返されます。 これらは、チェーン コンテキストの cLowerQualityChainContext フィールドと rgpLowerQualityChainContext フィールドで返されます。
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE
0x00000100
 このフラグを設定すると、Windows Update Web サーバーからのサードパーティルートの自動更新が禁止されます。
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT
0x08000000
 CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUTを設定し、CERT_CHAIN_PARA構造体のdwUrlRetrievalTimeout メンバーの値も指定すると、dwUrlRetrievalTimeout で指定した値は、すべての失効 URL 取得の累積タイムアウトを表します。

CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT設定しても dwUrlRetrievalTimeout 値を指定しない場合、既定では最大累積タイムアウトは 20 秒に設定されます。 テストされた各 URL は、残りの累積残高の半分が経過した後にタイムアウトします。 つまり、最初の URL は 10 秒後にタイムアウトし、2 番目の URL は 5 秒後、3 番目は 2.5 秒後にタイムアウトします。URL が成功するまで、20 秒が経過するか、テストする URL がもうありません。

CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUTを設定しない場合、チェーン内の各失効 URL には、 dwUrlRetrievalTimeout で指定された値と等しい最大タイムアウトが割り当てられます。 dwUrlRetrievalTimeout メンバーの値を指定しない場合、各失効 URL には最大 15 秒の既定のタイムアウトが割り当てられます。 URL が成功しない場合、最大累積タイムアウト値は 15 秒にチェーン内の URL の数を乗算します。

既定値は、グループ ポリシーを使用して設定できます。
CERT_CHAIN_TIMESTAMP_TIME
0x00000200
 このフラグを設定すると、終了証明書が有効な時刻かどうかを判断するために、タイム スタンプ時刻として pTime が使用されます。 現在の時刻を使用して、終了証明書が有効な時間のままかどうかを判断することもできます。 チェーン内の他のすべての 証明機関 (CA) とルート証明書は、 pTime ではなく現在の時刻を使用してチェックされます。
CERT_CHAIN_DISABLE_AIA
0x00002000
 このフラグを設定すると、機関情報アクセス (AIA) の取得が明示的にオフになります。
 

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

値 説明
CERT_CHAIN_REVOCATION_CHECK_END_CERT
0x10000000
 失効チェックは、終了証明書と終了証明書でのみ行われます。
CERT_CHAIN_REVOCATION_CHECK_CHAIN
0x20000000
 失効チェックは、すべてのチェーン内のすべての証明書で行われます。
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT
0x40000000
 失効チェックは、ルート証明書を除くすべてのチェーン内のすべての証明書で行われます。

[in] pvReserved

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

[out] ppChainContext

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

戻り値

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

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

解説

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

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

  • この関数の厳密な署名チェックを有効にするには、pChainPara パラメーターによって指されるCERT_CHAIN_PARA構造体の pStrongSignPara メンバーを設定します。
  • チェーンに厳密な署名のない証明書が見つかった場合、CERT_TRUST_STATUS構造体の dwErrorStatus フィールドにCERT_TRUST_HAS_WEAK_SIGNATUREエラーとCERT_TRUST_IS_NOT_SIGNATURE_VALID エラーが設定されます。 ppChainContext パラメーターは、CERT_CHAIN_CONTEXT構造体を指し、CERT_TRUST_STATUS構造体を指します。
  • チェーンが厳密に署名されている場合は、最終的な証明書の公開キーがチェックされ、厳密な署名の最小公開キーの長さの要件を満たしているかどうかを判断します。 条件が満たされない場合、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に設定されます。

例

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

要件

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

関連項目

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

証明書チェーン検証関数