From 1b3be66f48f27d8f1a1d358d632ac76b5a6b0603 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Fri, 29 Mar 2013 07:59:12 +0000
Subject: [PATCH] CR-1485 Fix for OPENDJ-841: Mention safe ways of building filters from user input in dev guide
---
opendj3/src/main/docbkx/dev-guide/index.xml | 4 ++--
opendj3/src/main/docbkx/dev-guide/chap-reading.xml | 37 +++++++++++++++++++++++++++++++++----
2 files changed, 35 insertions(+), 6 deletions(-)
diff --git a/opendj3/src/main/docbkx/dev-guide/chap-reading.xml b/opendj3/src/main/docbkx/dev-guide/chap-reading.xml
index f70c51d..badc6b8 100644
--- a/opendj3/src/main/docbkx/dev-guide/chap-reading.xml
+++ b/opendj3/src/main/docbkx/dev-guide/chap-reading.xml
@@ -20,7 +20,7 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2012 ForgeRock AS
+ ! Copyright 2011-2013 ForgeRock AS
!
-->
<chapter xml:id='chap-reading'
@@ -267,10 +267,39 @@
cases, the SDK translates the strings and objects into the binary
representation sent to the server over the network.</para>
- <para>Equality is just one of the types of comparisons available in LDAP
- filters. Comparison operators include the following.</para>
+ <para>Equality is just one of the types of comparisons available in LDAP
+ filters. Comparison operators include the following.</para>
- <xinclude:include href="../shared/table-filter-operators.xml" />
+ <xinclude:include href="../shared/table-filter-operators.xml" />
+
+ <para>When taking user input, take care to protect against users providing
+ input that has unintended consequences. OpenDJ SDK offers several Filter
+ methods to help you. First, you can use strongly typed construction methods
+ such as <literal>Filter.equality()</literal>.</para>
+
+ <programlisting language="java">String userInput = getUserInput();
+Filter filter = Filter.equality("cn", userInput);
+
+// Invoking filter.toString() with input of "*" results in a filter
+// string "(cn=\2A)".</programlisting>
+
+ <para>You can also let the SDK escape user input by using a template with
+ <literal>Filter.format()</literal> as in the following example.</para>
+
+ <programlisting language="java">String template = "(|(cn=%s)(uid=user.%s))";
+String[] userInput = getUserInput();
+Filter filter = Filter.format(template, userInput[0], userInput[1]);</programlisting>
+
+ <para>Finally, you can explicitly escape user input with
+ <literal>Filter.escapeAssertionValue()</literal>.</para>
+
+ <programlisting language="java">String baseDN = "ou=people,dc=example,dc=com";
+String userInput = getUserInput();
+
+// Filter.escapeAssertionValue() transforms user input of "*" to "\2A".
+SearchRequest request = Requests.newSearchRequest(
+ baseDN, SearchScope.WHOLE_SUBTREE,
+ "(cn=" + Filter.escapeAssertionValue(userInput) + "*)", "cn", "mail");</programlisting>
</section>
<section xml:id="send-search-request">
diff --git a/opendj3/src/main/docbkx/dev-guide/index.xml b/opendj3/src/main/docbkx/dev-guide/index.xml
index cba17f7..87fdc22 100644
--- a/opendj3/src/main/docbkx/dev-guide/index.xml
+++ b/opendj3/src/main/docbkx/dev-guide/index.xml
@@ -20,7 +20,7 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2012 ForgeRock AS
+ ! Copyright 2011-2013 ForgeRock AS
!
-->
<book xml:id='dev-guide'
@@ -36,7 +36,7 @@
OpenDJ project offers open source LDAP directory services in Java.</para>
</abstract>
<copyright>
- <year>2011-2012</year>
+ <year>2011-2013</year>
<holder>ForgeRock AS</holder>
</copyright>
<authorgroup>
--
Gitblit v1.10.0