Signatur
Beschreibung
ldap_escape() maskiert Sonderzeichen in einem String, sodass dieser sicher in LDAP-Abfragen (Filter oder DN) eingebettet werden kann. Ähnlich wie mysqli_real_escape_string() für SQL schützt diese Funktion vor LDAP-Injection-Angriffen, bei denen ein Angreifer die Struktur einer LDAP-Anfrage manipulieren könnte.
Der Kontext der Maskierung wird über das $flags-Argument gesteuert: LDAP_ESCAPE_FILTER maskiert Zeichen, die in LDAP-Filterausdrücken (RFC 4515) besondere Bedeutung haben, und LDAP_ESCAPE_DN maskiert Zeichen für Distinguished Names (RFC 4514). Beide Flags können mit dem bitweisen OR-Operator (|) kombiniert werden.
Über den Parameter $ignore lassen sich einzelne Zeichen von der Maskierung ausschließen, etwa wenn ein Filter bewusst Wildcards (*) enthalten soll. Dies ist jedoch mit Bedacht zu verwenden, da es das Sicherheitsniveau reduziert.
Die Funktion gibt den maskierten String zurück, der dann gefahrlos in ldap_search(), ldap_add() oder ähnliche LDAP-Operationen eingefügt werden kann.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value Pflicht | string | Der zu maskierende Eingabe-String, typischerweise ein benutzerseitig gelieferter Wert. | |
| $ignore | string | Zeichen, die nicht maskiert werden sollen. Z. B. '*' um Wildcards in LDAP-Suchen zu erlauben. Vorsicht: reduziert den Schutz vor Injection. |
|
| $flags | int | 0 | Bestimmt den Maskierungskontext. Mögliche Werte: LDAP_ESCAPE_FILTER (für Filter-Strings), LDAP_ESCAPE_DN (für Distinguished Names) oder eine Kombination beider Flags per |. Ohne Flag werden alle Sonderzeichen maskiert. |
Rückgabewert
\XX kodiert.Beispiele
Sichere LDAP-Filtersuche nach Benutzername
<?php
$ldapConn = ldap_connect('ldap://localhost');
ldap_bind($ldapConn);
// Benutzereingabe — könnte Sonderzeichen enthalten
$username = '(admin)*'; // potenziell bösartige Eingabe
$safeUsername = ldap_escape($username, '', LDAP_ESCAPE_FILTER);
$filter = "(uid={$safeUsername})";
echo $filter;
// Ausgabe: (uid=\28admin\29\2a)
$result = ldap_search($ldapConn, 'dc=example,dc=com', $filter);
?>Maskierung für Distinguished Name (DN)
<?php
$ldapConn = ldap_connect('ldap://localhost');
ldap_bind($ldapConn);
$cn = 'Müller, Hans (Admin)';
$safeCn = ldap_escape($cn, '', LDAP_ESCAPE_DN);
$dn = "cn={$safeCn},ou=users,dc=example,dc=com";
echo $dn;
// Ausgabe: cn=Müller\2c Hans \28Admin\29,ou=users,dc=example,dc=com
$entry = ['cn' => $cn, 'sn' => 'Müller', 'objectClass' => 'inetOrgPerson'];
ldap_add($ldapConn, $dn, $entry);
?>Wildcards bewusst erlauben
<?php
$ldapConn = ldap_connect('ldap://localhost');
ldap_bind($ldapConn);
// Benutzer darf Wildcard '*' verwenden, aber alle anderen Sonderzeichen werden maskiert
$search = 'admin*';
$safeSearch = ldap_escape($search, '*', LDAP_ESCAPE_FILTER);
$filter = "(uid={$safeSearch})";
echo $filter;
// Ausgabe: (uid=admin*)
?>// Wichtig · Fallstricke
Sicherheitshinweis: Vor PHP 5.6 gab es keine offizielle Funktion zur LDAP-Maskierung. Selbst geschriebene Lösungen waren oft unvollständig. Achte darauf, dass du immer das passende Flag (LDAP_ESCAPE_FILTER oder LDAP_ESCAPE_DN) verwendest — eine falsche Kombination kann zu unvollständiger Maskierung führen.
Der Parameter $ignore sollte nur verwendet werden, wenn du dir absolut sicher bist, dass die nicht maskierten Zeichen keine Sicherheitslücke erzeugen (z. B. bei kontrollierten Wildcard-Suchen mit *). Lass niemals benutzerdefinierte Werte ohne Maskierung in LDAP-Abfragen einfließen.
Ohne Angabe eines Flags ($flags = 0) werden alle bekannten LDAP-Sonderzeichen maskiert — dies ist die sicherste, aber auch restriktivste Variante.