LDAP filters: A String Representation of LDAP Search Filters
Writing LDAP search requests in plain text instead of network encoding
Howes, T., "A String Representation of LDAP Search Filters", RFC 1558, DOI 10.17487/RFC1558, December 1993, <https://www.rfc-editor.org/info/rfc1558>.
@misc{rfc1558,
series = {Request for Comments},
number = 1558,
howpublished = {RFC 1558},
publisher = {RFC Editor},
doi = {10.17487/RFC1558},
url = {https://www.rfc-editor.org/info/rfc1558},
author = {T. Howes},
title = {{A String Representation of LDAP Search Filters}},
pagetotal = 3,
year = 1993,
month = dec,
} RFC text
Contents
Network Working Group T. Howes
Request for Comments: 1558 University of Michigan
Category: Informational December 1993
A String Representation of LDAP Search Filters
Status of this Memo
This memo provides information for the Internet community. This memo
does not specify an Internet standard of any kind. Distribution of
this memo is unlimited.
Abstract
The Lightweight Directory Access Protocol (LDAP) [1] defines a
network representation of a search filter transmitted to an LDAP
server. Some applications may find it useful to have a common way of
representing these search filters in a human-readable form. This
document defines a human-readable string format for representing LDAP
search filters.
1. LDAP Search Filter Definition
An LDAP search filter is defined in [1] as follows:
Filter ::= CHOICE {
and [0] SET OF Filter,
or [1] SET OF Filter,
not [2] Filter,
equalityMatch [3] AttributeValueAssertion,
substrings [4] SubstringFilter,
greaterOrEqual [5] AttributeValueAssertion,
lessOrEqual [6] AttributeValueAssertion,
present [7] AttributeType,
approxMatch [8] AttributeValueAssertion
}
SubstringFilter ::= SEQUENCE {
type AttributeType,
SEQUENCE OF CHOICE {
initial [0] LDAPString,
any [1] LDAPString,
final [2] LDAPString
}
}
AttributeValueAssertion ::= SEQUENCE
attributeType AttributeType,
attributeValue AttributeValue
}
AttributeType ::= LDAPString
AttributeValue ::= OCTET STRING
LDAPString ::= OCTET STRING
where the LDAPString above is limited to the IA5 character set. The
AttributeType is a string representation of the attribute object
identifier in dotted OID format (e.g., "2.5.4.10"), or the shorter
string name of the attribute (e.g., "organizationName", or "o"). The
AttributeValue OCTET STRING has the form defined in [2]. The Filter
is encoded for transmission over a network using the Basic Encoding
Rules defined in [3], with simplifications described in [1].
2. String Search Filter Definition
The string representation of an LDAP search filter is defined by the
following BNF. It uses a prefix format.
<filter> ::= '(' <filtercomp> ')'
<filtercomp> ::= <and> | <or> | <not> | <item>
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist>
<not> ::= '!' <filter>
<filterlist> ::= <filter> | <filter> <filterlist>
<item> ::= <simple> | <present> | <substring>
<simple> ::= <attr> <filtertype> <value>
<filtertype> ::= <equal> | <approx> | <greater> | <less>
<equal> ::= '='
<approx> ::= '~='
<greater> ::= '>='
<less> ::= '<='
<present> ::= <attr> '=*'
<substring> ::= <attr> '=' <initial> <any> <final>
<initial> ::= NULL | <value>
<any> ::= '*' <starval>
<starval> ::= NULL | <value> '*' <starval>
<final> ::= NULL | <value>
<attr> is a string representing an AttributeType, and has the format
defined in [1]. <value> is a string representing an AttributeValue,
or part of one, and has the form defined in [2]. If a <value> must
contain one of the characters '*' or '(' or ')', these characters
should be escaped by preceding them with the backslash '\' character.
3. Examples
This section gives a few examples of search filters written using
this notation.
(cn=Babs Jensen)
(!(cn=Tim Howes))
(&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
(o=univ*of*mich*)
4. Security Considerations
Security issues are not discussed in this memo.
5. References
[1] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access
Protocol", RFC 1487, Performance Systems International,
University of Michigan, ISODE Consortium, July 1993.
[2] Howes, T., Kille, S., Yeong, W., and C. Robbins, "The String
Representation of Standard Attribute Syntaxes", RFC 1488,
University of Michigan, ISODE Consortium, Performance Systems
International, NeXor Ltd., July 1993.
[3] "Specification of Basic Encoding Rules for Abstract Syntax
Notation One (ASN.1)", CCITT Recommendation X.209, 1988.
6. Author's Address
Tim Howes
University of Michigan
ITD Research Systems
535 W William St.
Ann Arbor, MI 48103-4943
USA
Phone: +1 313 747-4454
EMail: tim@umich.edu
AI ELI5
On this page
§1Filters in Plain Text
The Lightweight Directory Access Protocol (LDAP) defines a network representation of search filters that is encoded using ASN.1 Basic Encoding Rules. This binary format is efficient for transmission but not human-readable. RFC 1558 defines a text string format that applications can use to write LDAP search filters in a common, readable way. The format is called prefix notation because operators and test types come before their operands.
LDAP searches are sent in a complicated computer code over the network. This document shows how to write them as plain text that people can read and understand.
§2The Filter String Format
A filter is enclosed in parentheses and consists of one or more comparisons or logical combinations. The logical operators are: & for AND (all conditions must match), | for OR (at least one must match), and ! for NOT (the condition must not match). A simple comparison uses the form attribute operator value, where the operator is = (equal), >= (greater or equal), <= (less or equal), or ~= (approximately equal). The =* operator tests whether an attribute is present. Substring matching uses wildcards where an asterisk character stands for any sequence of characters. Special characters (asterisk, parentheses, and backslash) must be escaped with a backslash.
Write conditions inside parentheses. Use ampersand for AND, pipe for OR, and exclamation for NOT. Write attribute equals value to test if something matches. Use the asterisk symbol as a wildcard for parts of words.
§3Examples of Filters
(cn=Babs Jensen) finds entries where the common name is exactly Babs Jensen. (!(cn=Tim Howes)) finds all entries except those with common name Tim Howes. (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))) combines: AND this entry is of class Person AND it has surname Jensen OR it has a common name starting with Babs J. (o=univ*of*mich*) matches organization names containing univ...of...mich in that order, such as University of Michigan.
These are real examples: 'find Babs Jensen', 'find anyone NOT named Tim Howes', 'find people whose last name is Jensen OR whose first name starts with Babs', and 'find universities with Michigan in the name'.
(cn=John Smith) Simple equality
(!(cn=Admin)) Negation (NOT)
(&(cn=John)(o=Acme)) Conjunction (AND)
(|(cn=John)(cn=Jane)) Disjunction (OR)
(cn=John*) Wildcard (starts with)
(cn=*Smith) Wildcard (ends with)
(cn=*ohn*) Wildcard (contains)
(cn=*)
Presence test (has attribute)