Метод IBackgroundCopyJobHttpOptions::SetClientCertificateByID (bits2_5.h)

  • Статья

Указывает идентификатор сертификата клиента, используемого для проверки подлинности клиента в HTTPS-запросе (SSL).

Синтаксис

HRESULT SetClientCertificateByID(
  [in] BG_CERT_STORE_LOCATION StoreLocation,
  [in] LPCWSTR                StoreName,
  [in] byte                   *pCertHashBlob
);

Параметры

[in] StoreLocation

Определяет расположение системного хранилища, используемого для поиска сертификата. Возможные значения см. в перечислении BG_CERT_STORE_LOCATION .

[in] StoreName

Строка, завершающаяся нулевым значением, которая содержит имя хранилища сертификатов. Длина строки ограничена 256 символами, включая признак конца null. Можно указать одно из следующих системных хранилищ или хранилище, определенное приложением. Хранилище может быть локальным или удаленным.

Значение Значение
CA
 Сертификаты центра сертификации
MY
 Личные сертификаты
КОРНЕВОЙ
 Корневые сертификаты
SPC
 сертификат издателя программного обеспечения

[in] pCertHashBlob

Хэш SHA1, идентифицирующий сертификат. Используйте буфер размером 20 байт для хэша. Дополнительные сведения см. в подразделе "Примечания".

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

В следующей таблице перечислены некоторые из возможных возвращаемых значений.

Код возврата Описание
S_OK
 Успешно.
E_ACCESSDENIED
 У пользователя нет разрешения на доступ к расположению хранилища.
E_NOTIMPL
 Значение параметра StoreLocation не определено в перечислении BG_CERT_STORE_LOCATION .
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
 Не удалось найти магазин, соответствующий параметру StoreName .
CRYPT_E_NOT_FOUND
 Сертификат, соответствующий хэшу, не найден.
RPC_X_NULL_REF_POINTER
 Параметр StoreName или pCertHashBlob не может иметь значение NULL.
RPC_X_BAD_STUB_DATA
 Размер буфера pCertHashBlob не равен 20 байтам.
BG_E_STRING_TOO_LONG
 Параметр StoreName содержит более 256 символов.
BG_E_INVALID_STATE
 Состояние задания не может быть BG_JOB_STATE_CANCELLED или BG_JOB_STATE_ACKNOWLEDGED.

Комментарии

Только владелец задания может указать сертификат клиента. Если задание меняет владение, BITS удаляет сертификат из задания.

Сертификат клиента применим только для удаленных файлов, использующих протокол HTTP или HTTPS. Сертификат можно указать для всех типов заданий.

Если веб-сайт принимает, но не требует SSL-сертификат клиента, а задание BITS не указывает сертификат клиента, задание завершится сбоем с ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED (0x80072f0c).

При создании сертификата для задания или приложения можно сохранить идентификатор сертификата (отпечаток) в реестре или базе данных и использовать его, когда для задания требуется сертификат. Вы также можете перечислить сертификаты в хранилище и позволить пользователю выбрать сертификат. Другой альтернативой является вызов функции CertFindCertificateInStore для получения контекста сертификата на основе некоторых критериев. Используя контекст, вызовите функцию CertGetCertificateContextProperty , чтобы получить хэш (укажите CERT_HASH_PROP_ID для dwPropId).

Отпечатки смарт-карт не поддерживаются.

Примеры

В следующем примере показано, как указать сертификат клиента для задания с помощью отпечатка сертификата. В примере жестко закодирует отпечаток сертификата и предполагается, что pJob указывает на допустимое задание.


  HRESULT hr = S_OK;
  IBackgroundCopyJob* pJob = NULL;  
  IBackgroundCopyJobHttpOptions* pHttpOptions = NULL;
  BYTE Thumbprint[] = {0xa1, 0x06, 0x6e, 0x13, 0xf2, 0x34, 0x49, 0x0a, 0x22, 0xd7, 0x6f, 0xb2, 0x80, 0xab, 0x68, 0x7d, 0x16, 0x55, 0xb3, 0x14};


  // Retrieve a pointer to the IBackgroundCopyJob4 interface.
  hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJobHttpOptions), (void**)&pHttpOptions);
  pJob->Release();
  if (FAILED(hr))
  {
    wprintf(L"QueryInterface for HttpOptions failed with 0x%x.\n", hr);
    goto cleanup;
  }

  // Use the client certificate in the current user's personal (MY) store.
  hr = pHttpOptions->SetClientCertificateByID(BG_CERT_STORE_LOCATION_CURRENT_USER, 
      L"MY", Thumbprint);
  if (FAILED(hr))
  {
    wprintf(L"pHttpOptions->SetClientCertificateByID failed with 0x%x.\n", hr);
    goto cleanup;
  }


cleanup:

  if (pHttpOptions)
  {
    hr = pHttpOptions->Release();
  }

Требования

Требование Значение
Минимальная версия клиента Windows Vista
Минимальная версия сервера Windows Server 2008
Целевая платформа Windows
Header bits2_5.h (включая Bits.h)
Библиотека Bits.lib

См. также раздел

IBackgroundCopyJobHttpOptions

IBackgroundCopyJobHttpOptions::GetClientCertificate

IBackgroundCopyJobHttpOptions::RemoveClientCertificate

IBackgroundCopyJobHttpOptions::SetClientCertificateByName