Поделиться через

Метод IBackgroundCopyServerCertificateValidationCallback::ValidateServerCertificate (bits10_3.h)

  • Статья

Метод обратного вызова, который будет вызываться таким образом, чтобы можно было проверить сертификаты сервера, отправленные при открытии подключения HTTPS.

Синтаксис

HRESULT ValidateServerCertificate(
  IBackgroundCopyJob  *job,
  IBackgroundCopyFile *file,
  DWORD               certLength,
  const BYTE []       certData,
  DWORD               certEncodingType,
  DWORD               certStoreLength,
  const BYTE []       certStoreData
);

Параметры

job

Тип: IBackgroundCopyJob*

Задание.

file

Тип: IBackgroundCopyFile*

Передаваемый файл.

certLength

Тип: DWORD

Длина в байтах данных сертификата.

certData

Тип: const BYTE []

Массив байтов, содержащий данные сертификата. Число байтов должно соответствовать certLength.

certEncodingType

Тип: DWORD

Тип кодирования сертификата.

certStoreLength

Тип: DWORD

Длина в байтах данных хранилища сертификатов.

certStoreData

Тип: const BYTE []

Массив байтов, содержащий данные хранилища сертификатов. Число байтов должно соответствовать certStoreLength.

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

Верните S_OK, чтобы указать, что сертификат является допустимым. В противном случае верните любой HRESULTкод ошибки, чтобы указать, что сертификат неприемлем.

Замечания

Проверка сертификата выполняется на двух этапах. Первым этапом является этап операционной системы ( ОС), где ОС выполняет стандартный набор проверок проверки сертификата. После этого, если этап ОС проходит сертификат, обратный вызов будет вызван для выполнения дополнительной проверки.

Реализуйте этот метод проверки, если требуется выполнить собственные проверки на сертификат сервера. Ваши собственные проверки в дополнение к обычным проверкам сертификата ОС.

Если метод проверки отклоняет сертификат, задание перейдет в BG_JOB_STATE_TRANSIENT_ERROR с контекстом ошибки задания BG_ERROR_CONTEXT_SERVER_CERTIFICATE_CALLBACK и ошибкой HRESULT из обратного вызова. Если обратный вызов не удалось вызвать (например, так как BITS требуется для проверки сертификата сервера после завершения программы), код ошибки задания будет BG_E_SERVER_CERT_VALIDATION_INTERFACE_REQUIRED. После следующего запуска приложения он может исправить эту ошибку, задав обратный вызов проверки еще раз и повторив задание.

BITS вызывает этот метод обратного вызова, только если вы реализуете интерфейс IBackgroundCopyServerCertificateValidationCallback и передаете его в IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface.

Интерфейс проверки становится недействительным при завершении работы приложения; BITS не поддерживает запись интерфейса проверки. В результате процесс инициализации приложения должен вызывать SetServerCertificateValidationInterface для существующих заданий, для которых требуется получать запросы на проверку сертификатов.

Если несколько вызовов приложений SetServerCertificateValidationInterface, чтобы задать интерфейс уведомлений для задания, последнее приложение для вызова — это тот, который получит уведомления. Другие приложения не будут получать уведомления.

Ниже приведены общие действия по проверке сертификата. Помните, что эти шаги являются лишь примером. Фактическая проверка находится под вашим контролем. Кроме того, шаги 5-7 в значительной степени совпадают с тем, что операционная система выполняет на этапе проверки ОС.

  1. Вызов CertCreateCertificateContext с certEncodingType, certDataи certLength для получения CERT_CONTEXT.

  2. Объявите и инициализируйте структуру CRYPT_DATA_BLOB (определенную в wincrypt.h) с сериализованным большим двоичным объектом памяти, передаваемым через certStoreLength и certStoreData.

DATA_BLOB storeData{};
storeData.cbData = certStoreLength;
storeData.pbData = const_cast<PBYTE>(certStoreData);
  1. Получите дескриптор в цепочке сертификатов, вызвав CertOpenStore с CERT_STORE_PROV_SERIALIZED, 0, nullptr, флагами и указателем на CRYPT_DATA_BLOB из шага 2.
  2. Получите указатель на контекст цепочки сертификатов, вызвав CertGetCertificateChain с nullptr, certContext, nullptr, дескриптор из шага 3, параметры цепочки, флаги и nullptr.
  3. Создайте политику проверки сертификата.
CERT_CHAIN_POLICY_PARA policyParams{};
policyParams.cbSize = sizeof(policyParams);
policyParams.dwFlags =
    CERT_CHAIN_POLICY_IGNORE_NOT_TIME_VALID_FLAG |
    CERT_CHAIN_POLICY_IGNORE_WRONG_USAGE_FLAG |
    CERT_CHAIN_POLICY_IGNORE_INVALID_NAME_FLAG |
    CERT_CHAIN_POLICY_ALLOW_UNKNOWN_CA_FLAG;
  1. Вызов CertVerifyCertificateChainPolicy с типом политики, контекстом цепочки, параметрами политики и состоянием политики.
  2. Преобразуйте ошибку Win32 (policyStatus.dwError) в HRESULT и верните это.

Ниже описано поведение кэширования проверки BITS. BITS поддерживает кэш сертификатов для каждого задания, прошедших настраиваемую проверку. Это позволяет избежать избыточной и потенциально дорогой повторной проверки за время существования задания. Кэш состоит из конечной точки сервера , кортежей хэша сертификатов, где конечной точки определяется как имя сервера :порт. Если задание уже позволило определенному сертификату из определенной конечной точки, обратный вызов не будет вызываться снова.

Конечно, сертификат должен пройти через логику проверки ОС при каждой попытке подключения (можно настроить логику проверки ОС с вызовом IBackgroundCopyJobHttpOptions::SetSecurityFlags), в котором рассматриваются случаи с учетом времени, например, когда сертификат был действителен в последнее время (с точки зрения секунд), но срок действия истек.

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

Кэш сертификатов задания очищается при каждом вызове SetServerCertificateValidationInterface, так как он указывает на то, что логика проверки сертификата сервера приложения изменилась.

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows 10 версии 1809 [только классические приложения]
минимальный поддерживаемый сервер Windows Server 2016 [только классические приложения]
заголовка bits10_3.h (include Bits.h)
библиотеки Bits.lib
DLL Bits.dll

См. также

IBackgroundCopyJobHttpOptions3::SetServerCertificateValidationInterface