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

Статья
02/23/2024

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

Синтаксис

HRESULT SetClientCertificateByName(
  [in] BG_CERT_STORE_LOCATION StoreLocation,
  [in] LPCWSTR                StoreName,
  [in] LPCWSTR                SubjectName
);

Параметры

[in] StoreLocation

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

[in] StoreName

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

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

[in] SubjectName

Строка, завершающаяся значением NULL, содержащая простое имя субъекта сертификата. Если имя субъекта содержит несколько относительных различающихся имен (RDN), можно указать один или несколько смежных RDN. Если указать несколько RDN, список будет разделен запятыми. Длина строки ограничена 256 символами, включая признак конца null. Невозможно указать пустое имя субъекта.

Не включайте идентификатор объекта в имя. Необходимо указать RDN в порядке, обратном от отображаемого в сертификате. Например, если имя субъекта в сертификате — "CN=name1, OU=name2, O=name3", укажите имя субъекта как "name3, name2, name1".

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

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

Код возврата	Описание
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 или SubjectName не может иметь значение NULL.
BG_E_STRING_TOO_LONG	Параметр StoreName или SubjectName содержит более 256 символов.
BG_E_INVALID_STATE	Состояние задания не может быть BG_JOB_STATE_CANCELLED или BG_JOB_STATE_ACKNOWLEDGED.

Метод использует строку имени субъекта для поиска сертификата в подстроке. Так как имена субъектов не обязательно являются уникальными, этот метод ищет в хранилище первый сертификат, который использует заданное имя субъекта и является сертификатом проверки подлинности клиента. Следует указать полное имя субъекта, чтобы повысить вероятность поиска одного совпадения. Если сертификат неверен (не является доверенным), задание завершится сбоем с BG_E_HTTP_ERROR_403, когда BITS попытается передать файл и задание переместится в состояние ошибки. Если вы не можете гарантировать уникальное имя субъекта, рассмотрите возможность использования метода IBackgroundCopyJobHttpOptions::SetClientCertificateByID .

Идентификаторы сертификатов SmartCard (отпечатки) не поддерживаются.

Примеры

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


  HRESULT hr = S_OK;
  IBackgroundCopyJob* pJob = NULL;
  IBackgroundCopyJobHttpOptions* pHttpOptions = NULL;

  // Change list of names to actual list of names.
  LPWSTR pSubjectName = L"name3, name2, name1";  
                                                    
  hr = pJob->QueryInterface(__uuidof(IBackgroundCopyJobHttpOptions), (void**)&pHttpOptions);
  pJob->Release();
  if (FAILED(hr))
  {
    wprintf(L"pJob->QueryInterface failed with 0x%x.\n", hr);
    goto cleanup;
  }

  // Use the client certificate in the current user's personal (MY) store.
  hr = pHttpOptions->SetClientCertificateByName(BG_CERT_STORE_LOCATION_CURRENT_USER, 
                                      L"MY", pSubjectName));
  if (FAILED(hr))
  {
    wprintf(L"pHttpOptions->SetClientCertificateByName 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::SetClientCertificateByID