WinVerifyTrust 関数 (wintrust.h)

  • [アーティクル]

WinVerifyTrust 関数は、指定したオブジェクトに対して信頼検証アクションを実行します。 この関数は、アクション識別子をサポートする 信頼プロバイダー (存在する場合) に照会を渡します。

証明書の検証には、 CertGetCertificateChain 関数と CertVerifyCertificateChainPolicy 関数を 使用します。

構文

LONG WinVerifyTrust(
  [in] HWND   hwnd,
  [in] GUID   *pgActionID,
  [in] LPVOID pWVTData
);

パラメーター

[in] hwnd

呼び出し元ウィンドウへの省略可能なハンドル。 信頼プロバイダーは、この値を使用して、ユーザーと対話できるかどうかを判断できます。 ただし、信頼プロバイダーは通常、ユーザーからの入力なしで検証アクションを実行します。

このパラメーターには、次の値のいずれかを指定できます。

値 意味
INVALID_HANDLE_VALUE
 対話型ユーザーはいません。 信頼プロバイダーは、ユーザーの支援なしに検証アクションを実行します。
Zero
 信頼プロバイダーは、対話型デスクトップを使用してそのユーザー インターフェイスを表示できます。
有効なウィンドウ ハンドル
 信頼プロバイダーは、INVALID_HANDLE_VALUEまたは 0 以外の任意の値を、ユーザーとの対話に使用できる有効なウィンドウ ハンドルとして扱うことができます。

[in] pgActionID

アクションを識別する GUID 構造体と、そのアクションをサポートする 信頼プロバイダー へのポインター。 この値は、 pWinTrustData が指す構造体に対して実行される検証アクションの種類を示します。

WinTrust サービスは、サード パーティによって実装された信頼プロバイダーと連携するように設計されています。 各信頼プロバイダーは、独自の一意のアクション識別子のセットを提供します。 信頼プロバイダーでサポートされているアクション識別子の詳細については、その信頼プロバイダーのドキュメントを参照してください。

たとえば、Microsoft は、インターネットまたはその他のパブリック ネットワークからダウンロードされるソフトウェアの信頼性を確立できるソフトウェア 発行元信頼プロバイダーを提供します。 ソフトウェア 発行元信頼プロバイダーでは、次のアクション識別子がサポートされています。 これらの定数は Softpub.h で定義されています。

値 意味
DRIVER_ACTION_VERIFY
 Windows Hardware Quality Labs (WHQL) 署名付きドライバーの信頼性を確認します。 これは Authenticode アドオン ポリシー プロバイダーです。
HTTPSPROV_ACTION
 インターネット エクスプローラーを介した SSL/TLS 接続を確認します。
OFFICESIGN_ACTION_VERIFY
 このアクション ID はサポートされていません。 Microsoft Office Authenticode アドオン ポリシー プロバイダーを使用して、構造化ストレージ ファイルの信頼性を確認します。

Windows Server 2003 および Windows XP: このアクション ID はサポートされています。
WINTRUST_ACTION_GENERIC_CHAIN_VERIFY
 任意のオブジェクトの種類から作成された証明書チェーンを確認します。 各署名者とカウンター署名者のチェーン コンテキストを使用して、最終的なチェーン ポリシーを実装するためのコールバックが提供されます。
WINTRUST_ACTION_GENERIC_VERIFY_V2
 Authenticode ポリシー プロバイダーを使用して、ファイルまたはオブジェクトを確認します。
WINTRUST_ACTION_TRUSTPROVIDER_TEST
 Authenticode ポリシー プロバイダーを呼び出した後、 CRYPT_PROVIDER_DATA 構造体をファイルに書き込みます。

[in] pWVTData

WINTRUST_DATA構造体としてキャストされるときに、信頼プロバイダーが指定したアクション識別子を処理するために必要な情報を含むポインター。 通常、 構造体には、信頼プロバイダーが評価する必要があるオブジェクトを識別する情報が含まれます。

構造体の形式は、アクション識別子によって異なります。 特定のアクション識別子に必要なデータについては、そのアクションをサポートする信頼プロバイダーのドキュメントを参照してください。

戻り値

信頼プロバイダーが、指定したアクションに対してサブジェクトが信頼されていることを確認した場合、戻り値は 0 です。 0 以外の他の値は、正常な戻り値と見なすべきではありません。

信頼プロバイダーが、指定したアクションに対してサブジェクトが信頼されていることを確認しない場合、関数は 信頼プロバイダーから状態コードを返します。

メモ 戻り値は LONG であり、前述のように HRESULT ではありません。 関数が成功したかどうかを判断するために、SUCCEEDED などの HRESULT マクロを使用しないでください。 代わりに、戻り値を 0 に等しくチェックします。

 

たとえば、信頼プロバイダーは、サブジェクトが信頼されていないか、信頼されているが制限または警告があることを示している可能性があります。 戻り値には、個々の信頼プロバイダーのドキュメントで説明されている信頼プロバイダー固有の値を指定できます。または、次のいずれかのエラー コードを指定できます。

リターン コード 説明
TRUST_E_SUBJECT_NOT_TRUSTED
 サブジェクトは、指定された検証アクションに失敗しました。 ほとんどの信頼プロバイダーは、エラーの理由を説明するより詳細なエラー コードを返します。
注  

TRUST_E_SUBJECT_NOT_TRUSTED戻りコードは、HKLM\Software\Microsoft\Cryptography\Wintrust\Config の EnableCertPaddingCheck レジストリ キーの値に応じて返される場合があります。EnableCertPaddingCheck が "1" に設定されている場合は、追加のチェックが実行され、WIN_CERTIFICATE構造体に余分な情報が含まれていないことを確認します。 チェックは、PKCS #7 構造体を超える 0 以外のデータがないことを検証します。 詳細については、次のセキュリティ アドバイザリを参照してください。 http://technet.microsoft.com/security/advisory/2915720#section1

 
TRUST_E_PROVIDER_UNKNOWN
 信頼プロバイダーはこのシステムでは認識されません。
TRUST_E_ACTION_UNKNOWN
 信頼プロバイダーは、指定されたアクションをサポートしていません。
TRUST_E_SUBJECT_FORM_UNKNOWN
 信頼プロバイダーは、サブジェクトに指定されたフォームをサポートしていません。

注釈

WinVerifyTrust 関数を使用すると、アプリケーションは信頼プロバイダーを呼び出して、指定したオブジェクトが指定した検証操作の条件を満たしていることを確認できます。 pgActionID パラメーターは検証操作を識別し、pWinTrustData パラメーターは信頼を検証するオブジェクトを識別します。 信頼プロバイダーは、オペレーティング システムに登録されている DLL です。 WinVerifyTrust への呼び出しは、指定されたアクション識別子をサポートする登録済み信頼プロバイダー (存在する場合) への呼び出しを転送します。

たとえば、ソフトウェア 発行元信頼プロバイダーは、実行可能イメージ ファイルが信頼されたソフトウェア発行元から取得されていること、およびファイルが発行されてから変更されていないことを確認できます。 この場合、 pWinTrustData パラメーターは、ファイルの名前とファイルの種類 (Microsoft ポータブル実行可能イメージ ファイルなど) を 指定します。

各信頼プロバイダーは、評価できる特定のアクション セットをサポートしています。 各アクションには、それを識別する GUID があります。 信頼プロバイダーは任意の数のアクション識別子をサポートできますが、2 つの信頼プロバイダーは同じアクション識別子をサポートできません。

この関数を使用して移植可能な実行可能ファイル (PE) ファイルの署名を検証する方法の例については、「 サンプル C プログラム: PE ファイルの署名の検証」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー wintrust.h (Softpub.h を含む)
Library Wintrust.lib
[DLL] Wintrust.dll