docs(LDAP): add info on stored DN form

Signed-off-by: Arthur Schiwon <blizzz@arthur-schiwon.de>

diff --git a/apps/user_ldap/lib/Access.php b/apps/user_ldap/lib/Access.php
index b6c5386fe62630b3a0f88bd4fdc6d64ee11108ef..c9f449d29f18818a2afdb277b533aea2d44b3941 100644 (file)
--- a/apps/user_ldap/lib/Access.php
+++ b/apps/user_ldap/lib/Access.php
@@ -279,6 +279,8 @@ class Access extends LDAPUtility {
         * Normalizes a result grom getAttributes(), i.e. handles DNs and binary
         * data if present.
         *
+        * DN values are escaped as per RFC 2253
+        *
         * @param array $result from ILDAPWrapper::getAttributes()
         * @param string $attribute the attribute name that was read
         * @return string[]
@@ -1260,6 +1262,8 @@ class Access extends LDAPUtility {
        /**
         * Executes an LDAP search
         *
+        * DN values in the result set are escaped as per RFC 2253
+        *
         * @throws ServerNotAvailableException
         */
        public function search(

diff --git a/apps/user_ldap/lib/Helper.php b/apps/user_ldap/lib/Helper.php
index 057a12cc0b50a07c90b9cd1fb6fc9d1faaa8b493..b9e5405d014a5a636b480039aeba48f88ad3933c 100644 (file)
--- a/apps/user_ldap/lib/Helper.php
+++ b/apps/user_ldap/lib/Helper.php
@@ -206,6 +206,21 @@ class Helper {
        /**
         * sanitizes a DN received from the LDAP server
         *
+        * This is used and done to have a stable format of DNs that can be compared
+        * and identified again. The input DN value is modified as following:
+        *
+        * 1) whitespaces after commas are removed
+        * 2) the DN is turned to lower-case
+        * 3) the DN is escaped according to RFC 2253
+        *
+        * When a future DN is supposed to be used as a base parameter, it has to be
+        * run through DNasBaseParameter() first, to recode \5c into a backslash
+        * again, otherwise the search or read operation will fail with LDAP error
+        * 32, NO_SUCH_OBJECT. Regular usage in LDAP filters requires the backslash
+        * being escaped, however.
+        *
+        * Internally, DNs are stored in their sanitized form.
+        *
         * @param array|string $dn the DN in question
         * @return array|string the sanitized DN
         */