IBackgroundCopyJobHttpOptions::SetClientCertificateByID-Methode (bits2_5.h)

Artikel
08/22/2023

Gibt den Bezeichner des Client-Zertifikats an, das für die Client-Authentifizierung in einer HTTPS (SSL)-Anfrage verwendet werden soll.

Syntax

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

Parameter

[in] StoreLocation

Gibt den Speicherort eines Systemspeichers an, der zum Suchen des Zertifikats verwendet werden soll. Mögliche Werte finden Sie in der BG_CERT_STORE_LOCATION-Enumeration .

[in] StoreName

Null-terminierte Zeichenfolge, die den Namen des Zertifikatspeichers enthält. Die Zeichenfolge ist auf 256 Zeichen beschränkt, einschließlich des NULL-Abschlusszeichens. Sie können einen der folgenden Systemspeicher oder einen anwendungsdefinierten Speicher angeben. Der Speicher kann ein lokaler Speicher oder ein Remotespeicher sein.

Wert	Bedeutung
CA	Zertifizierungsstellenzertifikate
MEINE	Persönliche Zertifikate
WURZEL	Stammzertifikate
SPC	Softwareherausgeberzertifikat

[in] pCertHashBlob

SHA1-Hash, der das Zertifikat identifiziert. Verwenden Sie einen 20-Byte-Puffer für den Hash. Weitere Informationen finden Sie in den Hinweisen.

Rückgabewert

In der folgenden Tabelle sind einige der möglichen Rückgabewerte aufgeführt.

Rückgabecode	Beschreibung
S_OK	Erfolg.
E_ACCESSDENIED	Der Benutzer verfügt nicht über die Berechtigung für den Zugriff auf den Speicherort.
E_NOTIMPL	Der Wert für den StoreLocation-Parameter ist in der BG_CERT_STORE_LOCATION-Enumeration nicht definiert.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	Es konnte kein Speicher gefunden werden, der mit dem StoreName-Parameter übereinstimmt.
CRYPT_E_NOT_FOUND	Ein Zertifikat, das dem Hash entspricht, wurde nicht gefunden.
RPC_X_NULL_REF_POINTER	Der StoreName - oder pCertHashBlob-Parameter darf nicht NULL sein.
RPC_X_BAD_STUB_DATA	Die Puffergröße pCertHashBlob beträgt nicht 20 Bytes.
BG_E_STRING_TOO_LONG	Der StoreName-Parameter umfasst mehr als 256 Zeichen.
BG_E_INVALID_STATE	Der Status des Auftrags kann nicht BG_JOB_STATE_CANCELLED oder BG_JOB_STATE_ACKNOWLEDGED werden.

Hinweise

Nur der Auftragsbesitzer kann das Clientzertifikat angeben. Wenn der Auftrag den Besitz ändert, entfernt BITS das Zertifikat aus dem Auftrag.

Das Clientzertifikat gilt nur für Remotedateien, die das HTTP- oder HTTPS-Protokoll verwenden. Sie können ein Zertifikat für alle Auftragstypen angeben.

Wenn eine Website ein SSL-Clientzertifikat akzeptiert, aber kein SSL-Clientzertifikat erfordert und der BITS-Auftrag kein Clientzertifikat angibt, schlägt der Auftrag mit ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED (0x80072f0c) fehl.

Wenn Sie ein Zertifikat für den Auftrag oder die Anwendung erstellen, können Sie den Zertifikatbezeichner (Fingerabdruck) in der Registrierung oder Datenbank speichern und verwenden, wenn für einen Auftrag ein Zertifikat erforderlich ist. Sie können auch die Zertifikate im Speicher aufzählen und dem Benutzer die Auswahl des Zertifikats überlassen. Eine weitere Alternative besteht darin, die CertFindCertificateInStore-Funktion aufzurufen, um den Zertifikatkontext basierend auf einigen Kriterien abzurufen. Rufen Sie mithilfe des Kontexts die CertGetCertificateContextProperty-Funktion auf, um den Hash abzurufen (geben Sie CERT_HASH_PROP_ID für dwPropId an).

SmartCard-Fingerabdruck werden nicht unterstützt.

Beispiele

Im folgenden Beispiel wird gezeigt, wie ein Clientzertifikat für einen Auftrag mithilfe des Fingerabdrucks des Zertifikats angegeben wird. Im Beispiel wird der Fingerabdruck des Zertifikats hart codieren und davon ausgegangen, dass pJob auf einen gültigen Auftrag verweist.


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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	bits2_5.h (Bits.h einschließen)
Bibliothek	Bits.lib