Metode IBackgroundCopyJobHttpOptions::SetClientCertificateByName (bits2_5.h)

Artikel
02/26/2024

Menentukan nama subjek sertifikat klien yang akan digunakan untuk autentikasi klien dalam permintaan HTTPS (SSL).

Sintaks

HRESULT SetClientCertificateByName(
  [in] BG_CERT_STORE_LOCATION StoreLocation,
  [in] LPCWSTR                StoreName,
  [in] LPCWSTR                SubjectName
);

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] SubjectName

String yang dihentikan null yang berisi nama subjek sederhana sertifikat. Jika nama subjek berisi beberapa nama yang dibedakan relatif (RDN), Anda dapat menentukan satu atau beberapa RDN yang berdekatan. Jika Anda menentukan lebih dari satu RDN, daftar dibatasi koma. String dibatasi hingga 256 karakter, termasuk terminator null. Anda tidak dapat menentukan nama subjek kosong.

Jangan sertakan pengidentifikasi objek dalam nama. Anda harus menentukan RDN dalam urutan terbalik dari apa yang ditampilkan sertifikat. Misalnya, jika nama subjek dalam sertifikat adalah "CN=name1, OU=name2, O=name3", tentukan nama subjek sebagai "name3, name2, name1".

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 StoreLocation tidak ditentukan dalam enumerasi BG_CERT_STORE_LOCATION .
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	Tidak dapat menemukan penyimpanan yang cocok dengan nilai parameter StoreName .
CRYPT_E_NOT_FOUND	Sertifikat yang cocok dengan nama subjek tidak ditemukan.
RPC_X_NULL_REF_POINTER	Parameter StoreName atau SubjectName tidak boleh NULL.
BG_E_STRING_TOO_LONG	Parameter StoreName atau SubjectName 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).

Metode ini menggunakan string nama subjek untuk melakukan pencarian substring untuk sertifikat. Karena nama subjek belum tentu unik, metode ini mencari penyimpanan untuk sertifikat pertama yang menggunakan nama subjek yang diberikan dan merupakan sertifikat autentikasi klien. Anda harus memberikan nama subjek lengkap untuk kesempatan yang lebih baik untuk menemukan satu kecocokan. Jika sertifikat tidak benar (tidak tepercaya), pekerjaan akan gagal dengan BG_E_HTTP_ERROR_403 ketika BITS mencoba mentransfer file dan pekerjaan akan pindah ke status kesalahan. Jika Anda tidak dapat menjamin nama subjek unik, pertimbangkan untuk menggunakan metode IBackgroundCopyJobHttpOptions::SetClientCertificateByID sebagai gantinya.

Pengidentifikasi sertifikat SmartCard (thumbprint) tidak didukung.

Contoh

Contoh berikut menunjukkan cara menentukan sertifikat klien untuk pekerjaan dengan menggunakan nama subjek sertifikat. Contoh mengasumsikan bahwa pJob menunjuk ke pekerjaan yang valid.


  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();
  }

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