IBackgroundCopyJobHttpOptions::SetClientCertificateByName-Methode (bits2_5.h)
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 |
|---|---|
|
Zertifizierungsstellenzertifikate |
|
Persönliche Zertifikate |
|
Stammzertifikate |
|
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 |
|---|---|
|
Erfolg. |
|
Der Benutzer verfügt nicht über die Berechtigung für den Zugriff auf den Speicherort. |
|
Der Wert für StoreLocation ist in der BG_CERT_STORE_LOCATION-Enumeration nicht definiert. |
|
Es konnte kein Speicher gefunden werden, der mit dem Wert des StoreName-Parameters übereinstimmt. |
|
Ein Zertifikat, das mit dem Antragstellernamen übereinstimmt, wurde nicht gefunden. |
|
Der StoreName- oder SubjectName-Parameter darf nicht NULL sein. |
|
Der StoreName- oder SubjectName-Parameter umfasst mehr als 256 Zeichen. |
|
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 |
Weitere Informationen
IBackgroundCopyJobHttpOptions::GetClientCertificate