docs(LDAP): add info on stored DN form

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

2 files changed, 19 insertions, 0 deletions

diff --git a/apps/user_ldap/lib/Access.php b/apps/user_ldap/lib/Access.php
index a51dfc3b349..931da301400 100644
--- 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 057a12cc0b5..b9e5405d014 100644
--- 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
 	 */