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 つ以上を組み合わせて使用できます。
| 価値 | 意味 |
|---|---|
CERT_CHAIN_CACHE_END_CERT0x00000001 |
このフラグを設定すると、エンド証明書がキャッシュされるため、チェーン構築プロセスが高速化される可能性があります。 既定では、終了証明書はキャッシュされないため、チェーンが構築されるたびに検証する必要があります。 |
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY0x80000000 |
失効チェックは、キャッシュされた URL にのみアクセスします。 これにより、エンド証明書または CA 証明書の CRL または OCSP のネットワーク取得ができなくなります。 CACHE_ONLY は、ネットワークから CRL または OCSP を既に取得しているマシン上の仲間に依存します。 |
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT0x04000000 |
このフラグは、循環失効チェックを防ぐために、オンライン証明書ステータス プロトコル (OCSP) 署名者証明書のチェーン構築中に内部的に使用されます。 チェーンの構築中に、OCSP 応答が独立した OCSP 署名者によって署名された場合、元のチェーン ビルドに加えて、OCSP 署名者証明書自体用に構築された 2 つ目のチェーンがあります。 このフラグは、再帰的に独立した OCSP 署名者証明書を禁止するために、この 2 番目のチェーンビルド中に使用されます。 署名者証明書に szOID_PKIX_OCSP_NOCHECK 拡張機能が含まれている場合、リーフ署名者証明書の失効チェックはスキップされます。 OCSP と CRL の両方のチェックが許可されます。 Windows Server 2003 および Windows XP: この値はサポートされていません。 |
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL0x00000004 |
証明書チェーンを構築する場合は、キャッシュされた URL のみを使用します。 インターネットとイントラネットでは、CTL cab、サード パーティのルート、AIA 発行者などの URL ベースのオブジェクトは検索されません。 ほとんどのルートは、crypt32.dll リソース内に存在する必要があります。 そうでない場合は、チェーン構築エラーを防ぐために、この取得が必要です。 これらのタクシーとルートは、高パフォーマンスの Microsoft CDN サーバーでホストされます。 注: このフラグは失効チェックには適用されません。 失効チェックにキャッシュされた URL のみを使用するように CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY を設定します。 通常、CTL cab は既に cryptsvc サービスを介して事前にフェッチされています。 |
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING0x00000040 |
パフォーマンス上の理由から、チェーン構築の 2 番目のパスでは、最初のパスで決定された最高品質以上の品質を持つ潜在的なチェーン パスのみが考慮されます。 最初のパスでは、チェーンの品質を計算するために有効な署名、完全なチェーン、信頼されたルートのみが考慮されます。 このフラグを設定すると、この最適化を無効にし、2 回目のパス中にすべての潜在的なチェーン パスを考慮できます。 |
CERT_CHAIN_DISABLE_MY_PEER_TRUST0x00000800 |
このフラグはサポートされていません。 "My" ストア内の証明書は、ピア信頼とは見なされません。 |
CERT_CHAIN_ENABLE_PEER_TRUST0x00000400 |
"TrustedPeople" ストアのエンド エンティティ証明書は、チェーン構築を実行せずに信頼されます。 この関数は、 Windows Server 2003 および Windows XP: このフラグはサポートされていません。 |
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE0x00010000 |
このフラグを設定すると、呼び出し元は弱い署名チェックをオプトインすることを望んでいる。 このフラグは、Windows 7 および Windows Server 2008 R2 以降の各 OS のロールアップ更新プログラムで使用できます。 |
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS0x00000080 |
既定値は、最高品質のチェーン パスのみを返します。 このフラグを設定すると、品質の低いチェーンが返されます。 これらは、 |
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE0x00000100 |
このフラグを設定すると、Windows Update Web Server からのサード パーティルートの自動更新が禁止されます。 |
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT0x08000000 |
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_TIME0x00000200 |
このフラグを設定すると、pTime がタイム スタンプ時刻として使用され、終了証明書が有効な時刻であったかどうかを判断します。 現在の時刻を使用して、終了証明書が有効な時間のままかどうかを判断することもできます。 チェーン内の他のすべての |
CERT_CHAIN_DISABLE_AIA0x00002000 |
このフラグを設定すると、機関情報アクセス (AIA) の取得が明示的にオフになります。 TLS サーバーが正しく構成されておらず、ハンドシェイクに正しい CA 証明書が含まれていない場合があります。 |
次の失効フラグを設定することもできますが、このグループのフラグは一度に 1 つだけ設定できます。
| 価値 | 意味 |
|---|---|
CERT_CHAIN_REVOCATION_CHECK_END_CERT0x10000000 |
失効チェックは、エンド証明書と終了証明書でのみ行われます。 |
CERT_CHAIN_REVOCATION_CHECK_CHAIN0x20000000 |
失効チェックは、すべてのチェーン内のすべての証明書で行われます。 |
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT0x40000000 |
失効チェックは、ルート証明書を除くすべてのチェーン内のすべての証明書で行われます。 |
[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 接続を行うのが一般的です。
-
CERT_CHAIN_CACHE_END_CERTを設定します。
例
この関数を使用する例については、「例 C プログラム: 証明書チェーンの作成」を参照してください。
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows XP [デスクトップ アプリ |UWP アプリ] |
| サポートされる最小サーバー | Windows Server 2003 [デスクトップ アプリ |UWP アプリ] |
| ターゲット プラットフォーム の |
ウィンドウズ |
| ヘッダー | wincrypt.h |
| ライブラリ | Crypt32.lib |
| DLL | Crypt32.dll |