IBackgroundCopyJobHttpOptions::SetClientCertificateByName-Methode (bits2_5.h)

Artikel
08/22/2023

Gibt den Antragstellernamen des Clientzertifikats an, das für die Clientauthentifizierung in einer HTTPS-Anforderung (SSL) verwendet werden soll.

Syntax

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

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

Null-terminierte Zeichenfolge, die den einfachen Antragstellernamen des Zertifikats enthält. Wenn der Antragstellername mehrere relative Distinguished Names (RDNs) enthält, können Sie ein oder mehrere angrenzende RDNs angeben. Wenn Sie mehrere RDN angeben, ist die Liste durch Trennzeichen getrennt. Die Zeichenfolge ist auf 256 Zeichen beschränkt, einschließlich des NULL-Abschlusszeichens. Sie können keinen leeren Antragstellernamen angeben.

Schließen Sie den Objektbezeichner nicht in den Namen ein. Sie müssen die RDNs in umgekehrter Reihenfolge für die Anzeige des Zertifikats angeben. Wenn der Antragstellername im Zertifikat beispielsweise "CN=Name1, OU=Name2, O=Name3" lautet, geben Sie den Antragstellernamen als "Name3, Name2, Name1" an.

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 StoreLocation 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 Wert des StoreName-Parameters übereinstimmt.
CRYPT_E_NOT_FOUND	Ein Zertifikat, das mit dem Antragstellernamen übereinstimmt, wurde nicht gefunden.
RPC_X_NULL_REF_POINTER	Der StoreName- oder SubjectName-Parameter darf nicht NULL sein.
BG_E_STRING_TOO_LONG	Der StoreName- oder SubjectName-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.

Die -Methode verwendet die Zeichenfolge des Antragstellernamens, um eine Teilzeichenfolge für das Zertifikat auszuführen. Da Antragstellernamen nicht notwendigerweise eindeutig sind, durchsucht diese Methode den Speicher nach dem ersten Zertifikat, das den angegebenen Antragstellernamen verwendet und ein Clientauthentifizierungszertifikat ist. Sie sollten den vollständigen Antragstellernamen angeben, um eine bessere Chance auf die Suche nach einer einzelnen Übereinstimmung zu erhalten. Wenn das Zertifikat nicht korrekt (nicht vertrauenswürdig) ist, schlägt der Auftrag mit BG_E_HTTP_ERROR_403 fehl, wenn BITS versucht, die Datei zu übertragen, und der Auftrag in den Fehlerzustand wechselt. Wenn Sie keinen eindeutigen Antragstellernamen garantieren können, sollten Sie stattdessen die IBackgroundCopyJobHttpOptions::SetClientCertificateByID-Methode verwenden.

SmartCard-Zertifikatbezeichner (Fingerabdruck) werden nicht unterstützt.

Beispiele

Im folgenden Beispiel wird gezeigt, wie Sie mithilfe des Antragstellernamens des Zertifikats ein Clientzertifikat für einen Auftrag angeben. Im Beispiel wird davon ausgegangen, dass pJob auf einen gültigen Auftrag verweist.


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

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