Metode IBackgroundCopyJobHttpOptions::SetClientCertificateByID (bits2_5.h)
Menentukan pengidentifikasi sertifikat klien yang akan digunakan untuk autentikasi klien dalam permintaan HTTPS (SSL).
Sintaks
HRESULT SetClientCertificateByID(
[in] BG_CERT_STORE_LOCATION StoreLocation,
[in] LPCWSTR StoreName,
[in] byte *pCertHashBlob
);
Parameter
[in] StoreLocation
Mengidentifikasi lokasi penyimpanan sistem yang akan digunakan untuk mencari sertifikat. Untuk nilai yang mungkin, lihat enumerasi BG_CERT_STORE_LOCATION .
[in] StoreName
String yang dihentikan null yang berisi nama penyimpanan sertifikat. String dibatasi hingga 256 karakter, termasuk terminator null. Anda dapat menentukan salah satu penyimpanan sistem berikut atau penyimpanan yang ditentukan aplikasi. Toko dapat berupa penyimpanan lokal atau jarak jauh.
Nilai | Makna |
---|---|
|
Sertifikat otoritas sertifikasi |
|
Sertifikat pribadi |
|
Sertifikat akar |
|
Sertifikat Penerbit Perangkat Lunak |
[in] pCertHashBlob
Hash SHA1 yang mengidentifikasi sertifikat. Gunakan buffer 20 byte untuk hash. Untuk informasi selengkapnya, lihat Keterangan.
Nilai kembali
Tabel berikut ini mencantumkan beberapa nilai yang mungkin dikembalikan.
Menampilkan kode | Deskripsi |
---|---|
|
Berhasil. |
|
Pengguna tidak memiliki izin untuk mengakses lokasi penyimpanan. |
|
Nilai untuk parameter StoreLocation tidak ditentukan dalam enumerasi BG_CERT_STORE_LOCATION . |
|
Tidak dapat menemukan penyimpanan yang cocok dengan parameter StoreName . |
|
Sertifikat yang cocok dengan hash tidak ditemukan. |
|
Parameter StoreName atau pCertHashBlob tidak boleh NULL. |
|
Ukuran buffer pCertHashBlob bukan 20 byte. |
|
Parameter StoreName lebih dari 256 karakter. |
|
Status pekerjaan tidak dapat BG_JOB_STATE_CANCELLED atau BG_JOB_STATE_ACKNOWLEDGED. |
Keterangan
Hanya pemilik pekerjaan yang dapat menentukan sertifikat klien. Jika pekerjaan mengubah kepemilikan, BITS akan menghapus sertifikat dari pekerjaan.
Sertifikat klien hanya berlaku untuk file jarak jauh yang menggunakan protokol HTTP atau HTTPS. Anda dapat menentukan sertifikat untuk semua jenis pekerjaan.
Ketika situs web menerima tetapi tidak memerlukan sertifikat klien SSL, dan pekerjaan BITS tidak menentukan sertifikat klien, pekerjaan akan gagal dengan ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED (0x80072f0c).
Jika Anda membuat sertifikat untuk pekerjaan atau aplikasi, Anda dapat menyimpan pengidentifikasi sertifikat (thumbprint) di registri atau database dan menggunakannya saat pekerjaan memerlukan sertifikat. Anda juga dapat menghitung sertifikat di penyimpanan dan membiarkan pengguna memilih sertifikat. Alternatif lain adalah memanggil fungsi CertFindCertificateInStore untuk mengambil konteks sertifikat berdasarkan beberapa kriteria. Dengan menggunakan konteks , panggil fungsi CertGetCertificateContextProperty untuk mengambil hash (tentukan CERT_HASH_PROP_ID untuk dwPropId).
Thumbprint SmartCard tidak didukung.
Contoh
Contoh berikut menunjukkan cara menentukan sertifikat klien untuk pekerjaan menggunakan thumbprint sertifikat. Contoh kode keras thumbprint sertifikat dan mengasumsikan pJob menunjuk ke pekerjaan yang valid.
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();
}
Persyaratan
Persyaratan | Nilai |
---|---|
Klien minimum yang didukung | Windows Vista |
Server minimum yang didukung | Windows Server 2008 |
Target Platform | Windows |
Header | bits2_5.h (termasuk Bits.h) |
Pustaka | Bits.lib |
Lihat juga
IBackgroundCopyJobHttpOptions::GetClientCertificate