Функция WinVerifyTrust (wintrust.h)

  • Статья

Функция WinVerifyTrust выполняет действие проверки доверия для указанного объекта. Функция передает запрос поставщику доверия , который поддерживает идентификатор действия, если он существует.

Для проверки сертификата используйте функции CertGetCertificateChain и CertVerifyCertificateChainPolicy .

Синтаксис

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

Параметры

[in] hwnd

Необязательный дескриптор для окна вызывающего абонента. Поставщик доверия может использовать это значение, чтобы определить, может ли он взаимодействовать с пользователем. Однако поставщики доверия обычно выполняют действия проверки без ввода данных от пользователя.

Этот параметр может принимать одно из указанных ниже значений.

Значение Значение
INVALID_HANDLE_VALUE
 Интерактивный пользователь отсутствует. Поставщик доверия выполняет действие проверки без помощи пользователя.
Нуль
 Поставщик доверия может использовать интерактивный рабочий стол для отображения своего пользовательского интерфейса.
Допустимый дескриптор окна
 Поставщик доверия может рассматривать любое значение, отличное от INVALID_HANDLE_VALUE или нуля, как допустимый дескриптор окна, который он может использовать для взаимодействия с пользователем.

[in] pgActionID

Указатель на структуру GUID , которая идентифицирует действие, и поставщик доверия , поддерживающий это действие. Это значение указывает тип действия проверки, выполняемого со структурой, на которую указывает pWinTrustData.

Служба WinTrust предназначена для работы с поставщиками доверия, реализованными третьими лицами. Каждый поставщик доверия предоставляет собственный уникальный набор идентификаторов действий. Сведения об идентификаторах действий, поддерживаемых поставщиком доверия, см. в документации для этого поставщика доверия.

Например, корпорация Майкрософт предоставляет поставщику доверия издателя программного обеспечения, который может установить надежность программного обеспечения, скачиваемого из Интернета или другой общедоступной сети. Поставщик доверия издателя программного обеспечения поддерживает следующие идентификаторы действий. Эти константы определены в Файле Softpub.h.

Значение Значение
DRIVER_ACTION_VERIFY
 Проверьте подлинность драйвера Windows Hardware Quality Labs (WHQL). Это поставщик политики надстройки Authenticode.
HTTPSPROV_ACTION
 Проверьте ssl/TLS-подключение через Интернет Обозреватель.
OFFICESIGN_ACTION_VERIFY
 Этот идентификатор действия не поддерживается. Проверьте подлинность структурированного файла хранилища с помощью поставщика политик надстройки Microsoft Office Authenticode.

Windows Server 2003 и Windows XP: Этот идентификатор действия поддерживается.
WINTRUST_ACTION_GENERIC_CHAIN_VERIFY
 Проверьте цепочки сертификатов, созданные из объектов любого типа. Предоставляется обратный вызов для реализации окончательной политики цепочки с использованием контекста цепочки для каждого подписывающего и подписывающего счетчика.
WINTRUST_ACTION_GENERIC_VERIFY_V2
 Проверьте файл или объект с помощью поставщика политики Authenticode.
WINTRUST_ACTION_TRUSTPROVIDER_TEST
 Запишите структуру CRYPT_PROVIDER_DATA в файл после вызова поставщика политик Authenticode.

[in] pWVTData

Указатель, который при приведение в качестве структуры WINTRUST_DATA содержит сведения, необходимые поставщику доверия для обработки указанного идентификатора действия. Как правило, структура содержит сведения, определяющие объект, который должен оценить поставщик доверия.

Формат структуры зависит от идентификатора действия. Сведения о данных, необходимых для определенного идентификатора действия, см. в документации по поставщику доверия, поддерживающему это действие.

Возвращаемое значение

Если поставщик доверия проверяет, является ли субъект доверенным для указанного действия, возвращаемое значение равно нулю. Никакие другие значения, кроме нуля, не должны считаться успешным возвратом.

Если поставщик доверия не проверяет, является ли субъект доверенным для указанного действия, функция возвращает код состояния от поставщика доверия.

Примечание Возвращаемое значение — LONG, а не HRESULT , как описано ранее. Не используйте макросы HRESULT , такие как SUCCEEDED, чтобы определить, успешно ли выполнена функция. Вместо этого проверка возвращаемое значение для равенства до нуля.

 

Например, поставщик доверия может указывать, что субъект не является доверенным или доверенным, но с ограничениями или предупреждениями. Возвращаемое значение может быть значением, зависящим от поставщика доверия, описанным в документации для отдельного поставщика доверия, или одним из следующих кодов ошибок.

Код возврата Описание
TRUST_E_SUBJECT_NOT_TRUSTED
 Субъект не выполнил указанное действие проверки. Большинство поставщиков доверия возвращают более подробный код ошибки, описывающий причину сбоя.
Примечание  

Код возврата TRUST_E_SUBJECT_NOT_TRUSTED может быть возвращен в зависимости от значения раздела реестра EnableCertPaddingCheck в разделе HKLM\Software\Microsoft\Cryptography\Wintrust\Config. Если параметр EnableCertPaddingCheck имеет значение "1", выполняется дополнительная проверка, чтобы убедиться, что структура WIN_CERTIFICATE не содержит посторонних сведений. Проверка проверяет отсутствие ненулевых данных за пределами структуры PKCS 7. Дополнительные сведения см. в следующих рекомендациях по безопасности: 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 указывает имя файла и тип файла, например файл образа переносимого исполняемого файла (Майкрософт).

Каждый поставщик доверия поддерживает определенный набор действий, которые он может оценить. Каждое действие имеет ИДЕНТИФИКАТОР GUID, который идентифицирует его. Поставщик доверия может поддерживать любое количество идентификаторов действий, но два поставщика доверия не могут поддерживать один и тот же идентификатор действия.

Пример использования этой функции для проверки сигнатуры переносимого исполняемого файла (PE) см. в разделе Пример программы C. Проверка подписи PE-файла.

Требования

Требование Значение
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Целевая платформа Windows
Header wintrust.h (включая Softpub.h)
Библиотека Wintrust.lib
DLL Wintrust.dll