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
包含证书存储名称的以 Null 结尾的字符串。 字符串限制为 256 个字符，包括 null 终止符。 可以指定以下系统存储或应用程序定义的存储之一。 存储可以是本地存储或远程存储。
| 值 | 含义 |
|---|---|
|
证书颁发机构证书 |
|
个人证书 |
|
根证书 |
|
软件发行者证书 |
[in] pCertHashBlob
用于标识证书的 SHA1 哈希。 将 20 字节缓冲区用于哈希。 有关详细信息，请参阅“备注”。
返回值
下表列出了一些可能的返回值。
| 返回代码 | 说明 |
|---|---|
|
成功。 |
|
用户没有访问存储位置的权限。 |
|
StoreLocation 参数的值未在 BG_CERT_STORE_LOCATION 枚举中定义。 |
|
找不到与 StoreName 参数匹配的存储。 |
|
找不到与哈希匹配的证书。 |
|
StoreName 或 pCertHashBlob 参数不能为 NULL。 |
|
pCertHashBlob 缓冲区大小不是 20 字节。 |
|
StoreName 参数超过 256 个字符。 |
|
作业的状态不能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 |
另请参阅
IBackgroundCopyJobHttpOptions：：GetClientCertificate