IBackgroundCopyJobHttpOptions：：SetClientCertificateByID 方法 (bits2_5.h)

项目
08/22/2023

指定要在 HTTPS (SSL) 请求中用于客户端身份验证的客户端证书的标识符。

语法

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

参数

[in] StoreLocation

标识用于查找证书的系统存储的位置。有关可能的值，请参阅 BG_CERT_STORE_LOCATION 枚举。

[in] StoreName

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

值	含义
约	证书颁发机构证书
我	个人证书
根	根证书
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 函数以检索哈希 (为 dwPropId) 指定CERT_HASH_PROP_ID。

不支持智能卡指纹。

示例

以下示例演示如何使用证书的指纹为作业指定客户端证书。该示例对证书的指纹进行硬编码，并假定 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
标头	bits2_5.h (包括 Bits.h)
Library	Bits.lib