This class provides a data structure that represents an LDAP search filter.
It provides methods for creating various types of filters, as well as parsing
a filter from a string. See
RFC 4515 for more
information about representing search filters as strings.
The following filter types are defined:
- AND -- This is used to indicate that a filter should match an
entry only if all of the embedded filter components match that entry.
An AND filter with zero embedded filter components is considered an
LDAP TRUE filter as defined in
RFC 4526 and will
match any entry. AND filters contain only a set of embedded filter
components, and each of those embedded components can itself be any
type of filter, including an AND, OR, or NOT filter with additional
embedded components.
- OR -- This is used to indicate that a filter should match an
entry only if at least one of the embedded filter components matches
that entry. An OR filter with zero embedded filter components is
considered an LDAP FALSE filter as defined in
RFC 4526 and will
never match any entry. OR filters contain only a set of embedded
filter components, and each of those embedded components can itself be
any type of filter, including an AND, OR, or NOT filter with additional
embedded components.
- NOT -- This is used to indicate that a filter should match an
entry only if the embedded NOT component does not match the entry. A
NOT filter contains only a single embedded NOT filter component, but
that embedded component can itself be any type of filter, including an
AND, OR, or NOT filter with additional embedded components.
- EQUALITY -- This is used to indicate that a filter should match
an entry only if the entry contains a value for the specified attribute
that is equal to the provided assertion value. An equality filter
contains only an attribute name and an assertion value.
- SUBSTRING -- This is used to indicate that a filter should match
an entry only if the entry contains at least one value for the
specified attribute that matches the provided substring assertion. The
substring assertion must contain at least one element of the following
types:
- subInitial -- This indicates that the specified string must
appear at the beginning of the attribute value. There can be at
most one subInitial element in a substring assertion.
- subAny -- This indicates that the specified string may appear
anywhere in the attribute value. There can be any number of
substring subAny elements in a substring assertion. If there are
multiple subAny elements, then they must match in the order that
they are provided.
- subFinal -- This indicates that the specified string must appear
at the end of the attribute value. There can be at most one
subFinal element in a substring assertion.
A substring filter contains only an attribute name and subInitial,
subAny, and subFinal elements.
- GREATER-OR-EQUAL -- This is used to indicate that a filter
should match an entry only if that entry contains at least one value
for the specified attribute that is greater than or equal to the
provided assertion value. A greater-or-equal filter contains only an
attribute name and an assertion value.
- LESS-OR-EQUAL -- This is used to indicate that a filter should
match an entry only if that entry contains at least one value for the
specified attribute that is less than or equal to the provided
assertion value. A less-or-equal filter contains only an attribute
name and an assertion value.
- PRESENCE -- This is used to indicate that a filter should match
an entry only if the entry contains at least one value for the
specified attribute. A presence filter contains only an attribute
name.
- APPROXIMATE-MATCH -- This is used to indicate that a filter
should match an entry only if the entry contains at least one value for
the specified attribute that is approximately equal to the provided
assertion value. The definition of "approximately equal to" may vary
from one server to another, and from one attribute to another, but it
is often implemented as a "sounds like" match using a variant of the
metaphone or double-metaphone algorithm. An approximate-match filter
contains only an attribute name and an assertion value.
- EXTENSIBLE-MATCH -- This is used to perform advanced types of
matching against entries, according to the following criteria:
- If an attribute name is provided, then the assertion value must
match one of the values for that attribute (potentially including
values contained in the entry's DN). If a matching rule ID is
also provided, then the associated matching rule will be used to
determine whether there is a match; otherwise the default
equality matching rule for that attribute will be used.
- If no attribute name is provided, then a matching rule ID must be
given, and the corresponding matching rule will be used to
determine whether any attribute in the target entry (potentially
including attributes contained in the entry's DN) has at least
one value that matches the provided assertion value.
- If the dnAttributes flag is set, then attributes contained in the
entry's DN will also be evaluated to determine if they match the
filter criteria. If it is not set, then attributes contained in
the entry's DN (other than those contained in its RDN which are
also present as separate attributes in the entry) will not be
examined.
An extensible match filter contains only an attribute name, matching
rule ID, dnAttributes flag, and an assertion value.
There are two primary ways to create a search filter. The first is to create
a filter from its string representation with the
Filter#create(String) method, using the syntax described in RFC 4515.
For example:
Filter f1 = Filter.create("(objectClass=*)");
Filter f2 = Filter.create("(uid=john.doe)");
Filter f3 = Filter.create("(|(givenName=John)(givenName=Johnathan))");
Creating a filter from its string representation is a common approach and
seems to be relatively straightforward, but it does have some hidden dangers.
This primarily comes from the potential for special characters in the filter
string which need to be properly escaped. If this isn't done, then the
search may fail or behave unexpectedly, or worse it could lead to a
vulnerability in the application in which a malicious user could trick the
application into retrieving more information than it should have. To avoid
these problems, it may be better to construct filters from their individual
components rather than their string representations, like:
Filter f1 = Filter.createPresenceFilter("objectClass");
Filter f2 = Filter.createEqualityFilter("uid", "john.doe");
Filter f3 = Filter.createORFilter(
Filter.createEqualityFilter("givenName", "John"),
Filter.createEqualityFilter("givenName", "Johnathan"));
In general, it is recommended to avoid creating filters from their string
representations if any of that string representation may include
user-provided data or special characters including non-ASCII characters,
parentheses, asterisks, or backslashes.