ldap_start_tls_sA-Funktion (winldap.h)

Die ldap_start_tls_s-Funktion wird in einer aktiven LDAP-Sitzung verwendet, um mit der Verwendung der TLS-Verschlüsselung zu beginnen.

Syntax

WINLDAPAPI ULONG LDAPAPI ldap_start_tls_sA(
  [in]  PLDAP         ExternalHandle,
  [out] PULONG        ServerReturnValue,
  [out] LDAPMessage   **result,
  [in]  PLDAPControlA *ServerControls,
  [in]  PLDAPControlA *ClientControls
);

Parameter

[in] ExternalHandle

Ein Zeiger auf eine LDAP--Struktur, die die aktuelle Sitzung darstellt.

[out] ServerReturnValue

Wahlfrei. Ein Zeiger auf eine ULONG-, die möglicherweise einen Serverfehlercode enthalten kann. Dieser Parameter sollte konsultiert werden, wenn LDAP_OTHER im Rückgabewert zurückgegeben wird. Übergeben Sie NULL-, wenn Sie sie nicht verwenden möchten.

[out] result

Wahlfrei. Ein Zeiger auf einen Zeiger für eine LDAPMessage- Struktur, die eine Serververweisnachricht enthalten kann. Übergeben Sie NULL-, wenn Sie sie nicht verwenden möchten.

[in] ServerControls

Wahlfrei. Ein NULL-beendetes Array von Zeigern auf LDAPControl- Strukturen, die Serversteuerelemente darstellen. Übergeben Sie NULL-, wenn Sie keine Serversteuerelemente angeben möchten.

[in] ClientControls

Wahlfrei. Ein NULL-beendetes Array von Zeigern auf LDAPControl- Strukturen, die Clientsteuerelemente darstellen. Übergeben Sie NULL-, wenn Sie keine Clientsteuerelemente angeben möchten.

Rückgabewert

Wenn der Funktionsaufruf erfolgreich ist, wird LDAP_SUCCESS zurückgegeben. LDAP_UNWILLING_TO_PERFORM wird zurückgegeben, wenn eine TLD/SSL-Sitzung bereits ausgeführt wird oder ob eine Bindung derzeit ausgeführt wird oder ob eine ausstehende LDAP-Anforderung für die Verbindung vorhanden ist. Wenn der Server den erweiterten Vorgang ablehnt, wird LDAP_OTHER zurückgegeben, und der ServerReturnValue Parameter sollte auf den Serverfehlercode überprüft werden.

Bemerkungen

Die ldap_start_tls_s-Funktion wird für eine vorhandene LDAP-Sitzung aufgerufen, um die Verwendung der TLS-Verschlüsselung (SSL) zu initiieren. Die Verbindung darf noch keine TLS-Verschlüsselung (SSL) aktiviert haben, und weder signieren noch versiegeln können bereits aktiviert werden. Außerdem kann eine Bindung für die Verbindung derzeit nicht ausgeführt werden, und es gibt keine ausstehenden LDAP-Anforderungen für die Verbindung. Wenn diese Bedingungen nicht erfüllt sind, wird LDAP_UNWILLING_TO_PERFORM zurückgegeben. Wenn diese Bedingungen erfüllt sind, sendet die Funktion den entsprechenden erweiterten Vorgang an den Server, um TLS (SSL) zu initiieren und dann die Verschlüsselung mit dem Server auszuhandeln. Wenn der Server den erweiterten Vorgang ablehnt, wird LDAP_OTHER zurückgegeben, und die ServerReturnValue- sollte überprüft werden, um den Serverfehlercode abzurufen.

Es ist möglich, dass der Server als Reaktion auf diesen Aufruf eine Empfehlung zurückgibt. Aus Sicherheitsgründen wird die Empfehlung nicht automatisch gejagt. Ein Zeiger auf die Empfehlungsnachricht wird im Ergebnis Parameter zurückgegeben.

Nachdem ldap_start_tls_s aufgerufen wurde, werden automatische Weiterleitungsnachfolgen und Autoreconnecting für die Verbindung deaktiviert. Sie werden nach erfolgreichem Abschluss des ldap_stop_tls_s Vorgangs in ihre vorherigen Einstellungen wiederhergestellt.

Diese Funktion hat ein Standardtimeout von etwa dreißig Sekunden. Dieses Timeout wird verwendet, um auf Antworten vom Server für den erweiterten TLS-Vorgang starten und während der TLS-Aushandlung (SSL) zu warten.

Weitere Informationen zur START-Stop-TLS-Verschlüsselung finden Sie unter Using Start-Stop TLS Encryption.

Anmerkung

Der winldap.h-Header definiert ldap_start_tls_s als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista
mindestens unterstützte Server-	Windows Server 2008
Zielplattform-	Fenster
Header-	winldap.h
Library	Wldap32.lib
DLL-	Wldap32.dll

Siehe auch

Verwenden Start-Stop TLS-Verschlüsselungs-

ldap_stop_tls_s