Metode IBackgroundCopyJobHttpOptions::SetClientCertificateByID (bits2_5.h)

  • Artikel

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
CA
 Sertifikat otoritas sertifikasi
SAYA
 Sertifikat pribadi
AKAR
 Sertifikat akar
SPC
 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
S_OK
 Berhasil.
E_ACCESSDENIED
 Pengguna tidak memiliki izin untuk mengakses lokasi penyimpanan.
E_NOTIMPL
 Nilai untuk parameter StoreLocation tidak ditentukan dalam enumerasi BG_CERT_STORE_LOCATION .
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)
 Tidak dapat menemukan penyimpanan yang cocok dengan parameter StoreName .
CRYPT_E_NOT_FOUND
 Sertifikat yang cocok dengan hash tidak ditemukan.
RPC_X_NULL_REF_POINTER
 Parameter StoreName atau pCertHashBlob tidak boleh NULL.
RPC_X_BAD_STUB_DATA
 Ukuran buffer pCertHashBlob bukan 20 byte.
BG_E_STRING_TOO_LONG
 Parameter StoreName lebih dari 256 karakter.
BG_E_INVALID_STATE
 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

IBackgroundCopyJobHttpOptions::GetClientCertificate

IBackgroundCopyJobHttpOptions::RemoveClientCertificate

IBackgroundCopyJobHttpOptions::SetClientCertificateByName