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

包含证书存储区名称的以 Null 结尾的字符串。字符串限制为 256 个字符，包括 null 终止符。可以指定以下系统存储或应用程序定义的存储区之一。存储可以是本地存储或远程存储。

值	含义
约	证书颁发机构证书
我	个人证书
根	根证书
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。

注解

只有作业所有者可以指定客户端证书。如果作业更改所有权，BITS 将从作业中删除证书。

客户端证书仅适用于使用 HTTP 或 HTTPS 协议的远程文件。可以为所有作业类型指定证书。

如果网站接受但不需要 SSL 客户端证书，并且 BITS 作业未指定客户端证书，则作业将失败并ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED (0x80072f0c) 。

方法使用使用者名称字符串对证书执行子字符串搜索。由于使用者名称不一定是唯一的，因此此方法在存储中搜索使用给定使用者名称且是客户端身份验证证书的第一个证书。应提供完整的使用者名称，以便更好地找到单个匹配项。如果证书不正确 (不受信任的) ，则当 BITS 尝试传输文件时，作业将失败并出现BG_E_HTTP_ERROR_403，并且作业将进入错误状态。如果不能保证使用者名称是唯一的，请考虑改用 IBackgroundCopyJobHttpOptions：：SetClientCertificateByID 方法。

不支持智能卡证书标识符 (指纹) 。

示例

以下示例演示如何使用证书的使用者名称为作业指定客户端证书。该示例假定 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
标头	bits2_5.h (包括 Bits.h)
Library	Bits.lib