draft-ietf-asid-ldapv3-filter-00.txt   draft-ietf-asid-ldapv3-filter-01.txt 
Network Working Group Tim Howes Network Working Group Tim Howes
INTERNET DRAFT Netscape Communications Corp. INTERNET DRAFT Netscape Communications Corp.
Expire in six months Expires in six months
The String Representation of LDAP Search Filters The String Representation of LDAP Search Filters
<draft-ietf-asid-ldapv3-filter-00.txt> <draft-ietf-asid-ldapv3-filter-01.txt>
1. Status of this Memo 1. Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working docu- This document is an Internet-Draft. Internet-Drafts are working docu-
ments of the Internet Engineering Task Force (IETF), its areas, and its ments of the Internet Engineering Task Force (IETF), its areas, and its
working groups. Note that other groups may also distribute working working groups. Note that other groups may also distribute working
documents as Internet-Drafts. documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
skipping to change at page 1, line 43 skipping to change at page 2, line 7
these search filters in a human-readable form. This document defines a these search filters in a human-readable form. This document defines a
human-readable string format for representing LDAP search filters. human-readable string format for representing LDAP search filters.
This document replaces RFC 1960, extending the string LDAP filter defin- This document replaces RFC 1960, extending the string LDAP filter defin-
ition to include support for LDAP version 3 extended match filters, and ition to include support for LDAP version 3 extended match filters, and
including support for representing the full range of possible LDAP including support for representing the full range of possible LDAP
search filters. search filters.
3. LDAP Search Filter Definition 3. LDAP Search Filter Definition
An LDAPv3 search filter is defined in [1] as follows: An LDAPv3 search filter is defined in Section 4.5.1 of [1] as follows:
Filter ::=3D CHOICE { Filter ::= CHOICE {
and [0] SET OF Filter, and [0] SET OF Filter,
or [1] SET OF Filter, or [1] SET OF Filter,
not [2] Filter, not [2] Filter,
=0C
equalityMatch [3] AttributeValueAssertion, equalityMatch [3] AttributeValueAssertion,
substrings [4] SubstringFilter, substrings [4] SubstringFilter,
greaterOrEqual [5] AttributeValueAssertion, greaterOrEqual [5] AttributeValueAssertion,
lessOrEqual [6] AttributeValueAssertion, lessOrEqual [6] AttributeValueAssertion,
present [7] AttributeDescription, present [7] AttributeDescription,
approxMatch [8] AttributeValueAssertion, approxMatch [8] AttributeValueAssertion,
extensibleMatch [9] MatchingRuleAssertion extensibleMatch [9] MatchingRuleAssertion
} }
SubstringFilter ::=3D SEQUENCE { SubstringFilter ::= SEQUENCE {
type AttributeDescription, type AttributeDescription,
SEQUENCE OF CHOICE { SEQUENCE OF CHOICE {
initial [0] LDAPString, initial [0] LDAPString,
any [1] LDAPString, any [1] LDAPString,
final [2] LDAPString final [2] LDAPString
} }
} }
AttributeValueAssertion ::=3D SEQUENCE { AttributeValueAssertion ::= SEQUENCE {
attributeDesc AttributeDescription, attributeDesc AttributeDescription,
attributeValue AttributeValue attributeValue AttributeValue
} }
MatchingRuleAssertion ::=3D SEQUENCE { MatchingRuleAssertion ::= SEQUENCE {
matchingRule [1] MatchingRuleID OPTIONAL, matchingRule [1] MatchingRuleID OPTIONAL,
type [2] AttributeDescription OPTIONAL, type [2] AttributeDescription OPTIONAL,
matchValue [3] AssertionValue, matchValue [3] AssertionValue,
dnAttributes [4] BOOLEAN DEFAULT FALSE dnAttributes [4] BOOLEAN DEFAULT FALSE
} }
AttributeDescription ::=3D LDAPString AttributeDescription ::= LDAPString
AttributeValue ::=3D OCTET STRING AttributeValue ::= OCTET STRING
MatchingRuleID ::=3D LDAPString MatchingRuleID ::= LDAPString
AssertionValue ::=3D OCTET STRING AssertionValue ::= OCTET STRING
LDAPString ::=3D OCTET STRING LDAPString ::= OCTET STRING
where the LDAPString above is limited to the UTF-8 encoding of the ISO where the LDAPString above is limited to the UTF-8 encoding of the ISO
10646 [4] character set. The AttributeDescription is a string represen- 10646 [4] character set. The AttributeDescription is a string represen-
tation of the attribute description name and is defined in [1]. The tation of the attribute description name and is defined in [1]. The
AttributeValue and AssertionValue OCTET STRING have the form defined in AttributeValue and AssertionValue OCTET STRING have the form defined in
[2]. The Filter is encoded for transmission over a network using the [2]. The Filter is encoded for transmission over a network using the
Basic Encoding Rules defined in [3], with simplifications described in Basic Encoding Rules defined in [3], with simplifications described in
[1]. [1].
=0C
4. String Search Filter Definition 4. String Search Filter Definition
The string representation of an LDAP search filter is defined by the The string representation of an LDAP search filter is defined by the
following grammar. The filter format uses a prefix notation. following grammar, following the ABNF notation defined in [5]. The
filter format uses a prefix notation.
<filter> ::=3D '(' <filtercomp> ')' filter = "(" filtercomp ")"
<filtercomp> ::=3D <and> | <or> | <not> | <item> filtercomp = and / or / not / item
<and> ::=3D '&' <filterlist> and = "&" filterlist
<or> ::=3D '|' <filterlist> or = "|" filterlist
<not> ::=3D '!' <filter> not = "!" filter
<filterlist> ::=3D <filter> | <filter> <filterlist> filterlist = 1*filter
<item> ::=3D <simple> | <present> | <substring> | <extensible> item = simple / present / substring / extensible
<simple> ::=3D <attr> <filtertype> <value> simple = attr filtertype value
<filtertype> ::=3D <equal> | <approx> | <greater> | <less> filtertype = equal / approx / greater / less
<equal> ::=3D '=3D' equal = "="
<approx> ::=3D '~=3D' approx = "~="
<greater> ::=3D '>=3D' greater = ">="
<less> ::=3D '<=3D' less = "<="
<extensible> ::=3D ( NULL | <attr> ) [ ':dn' ] [ ':' <matchingrule> = extensible = attr [":dn"] [":" matchingrule] ":=" value
] / [":dn"] ":" matchingrule ":=" value
':=3D' <value> present = attr "=*"
<matchingrule> ::=3D <matchingrulename> | <oid> substring = attr "=" [initial] any [final]
<matchingrulename> ::=3D <string> initial = value
<oid> ::=3D <string> any = "*" *(value "*")
<present> ::=3D <attr> '=3D*' final = value
<substring> ::=3D <attr> '=3D' <initial> <any> <final> attr = AttributeDescription from Section 4.1.5 of [1]
<initial> ::=3D NULL | <value> matchingrule = MatchingRuleId from Section 4.1.9 of [1]
<any> ::=3D '*' <starval> value = AttributeValue from Section 4.1.6 of [1]
<starval> ::=3D NULL | <value> '*' <starval>
<final> ::=3D NULL | <value>
<attr> is a string representing an AttributeDescription, and has the The attr, matchingrule, and value constructs are as described in the
format defined in [1]. <value> is a string representing an Attribu- corresponding section of [1] given above.
teValue, or part of one, and has the form defined in [2].
If a <value> should contain any of the characters '*' (ASCII 0x2a) or If a value should contain any of the following characters
0x00), the character must be encoded as the backslash '\' character fol-
lowed by the two hexadecimal digits representing the encoded character. Character ASCII value
---------------------------
* 0x2a
( 0x28
) 0x29
\ 0x5c
NUL 0x00
the character must be encoded as the backslash '\' character followed by
the two hexadecimal digits representing the ASCII value of the encoded
character.
This simple escaping mechanism eliminates filter-parsing ambiguities and This simple escaping mechanism eliminates filter-parsing ambiguities and
allows the construction of any filter that can be represented in LDAP. allows any filter that can be represented in LDAP to be represented as a
The case of the two hexadecimal digits is not significant. Other charac- NUL-terminated string. The case of the two hexadecimal digits is not
ters besides the ones listed above may be escaped using this mechanism, significant. Other characters besides the ones listed above may be
for example, non-printing characters. escaped using this mechanism, for example, non-printing characters.
For example, the filter checking whether the "cn" attribute contained a For example, the filter checking whether the "cn" attribute contained a
value with the character "*" anywhere in it would be represented as value with the character "*" anywhere in it would be represented as
"(cn=3D*2a*)". "(cn=*\2a*)".
=0C
Note that although both the <substring> and <present> productions can
produce the 'attr=3D*' construct, this construct is used only to denote =
a
presence filter.
<oid> is a dotted string representation of an object identifier (e.g., Note that although both the substring and present productions in the
"1.2.3.4") identifying a matching rule to use when comparing <value>. grammar above can produce the "attr=*" construct, this construct is used
<matchingrulename> is a name given to a matching rule, as defined in only to denote a presence filter.
[2]. One of <attr> or <matchingrule> is required in the <extensible>
production.
5. Examples 5. Examples
This section gives a few examples of search filters written using this This section gives a few examples of search filters written using this
notation. notation.
(cn=3DBabs Jensen) (cn=Babs Jensen)
(!(cn=3DTim Howes)) (!(cn=Tim Howes))
(&(objectClass=3DPerson)(|(sn=3DJensen)(cn=3DBabs J*))) (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
(o=3Duniv*of*mich*) (o=univ*of*mich*)
The following examples illustrate the use of extensible matching. The following examples illustrate the use of extensible matching.
(cn:1.2.3.4.5:=3DFred Flintstone) (cn:1.2.3.4.5:=Fred Flintstone)
(sn:dn:2.4.6.8.10:=3DBarney Rubble) (sn:dn:2.4.6.8.10:=Barney Rubble)
(o:dn:=3DAce Industry) (o:dn:=Ace Industry)
The second example illustrates the use of the ":dn" notation to indicate The second example illustrates the use of the ":dn" notation to indicate
that matching rule "2.4.6.8.10" should be used when making comparisons, that matching rule "2.4.6.8.10" should be used when making comparisons,
and that the attributes of an entry's distinguished name should be con- and that the attributes of an entry's distinguished name should be con-
sidered part of the entry when evaluating the match. sidered part of the entry when evaluating the match.
The third example denotes an equality match, except that DN components The third example denotes an equality match, except that DN components
should be considered part of the entry when doing the match. should be considered part of the entry when doing the match.
The following examples illustrate the use of the escaping mechanism. The following examples illustrate the use of the escaping mechanism.
(o=3DParens R Us \28for all your parenthetical needs\29) (o=Parens R Us \28for all your parenthetical needs\29)
(cn=3D*\2A*) (cn=*\2A*)
(filename=3DC:\5cMyFile) (filename=C:\5cMyFile)
(bin=3D\00\00\00\04) (bin=\00\00\00\04)
(sn=3DLu\c4\8di\c4\c7) (sn=Lu\c4\8di\c4\c7)
The first example shows the use of the escaping mechanism to represent The first example shows the use of the escaping mechanism to represent
parenthesis characters. The second shows how to represent a "*" in a parenthesis characters. The second shows how to represent a "*" in a
value, preventing it from being interpreted as a substring indicator. value, preventing it from being interpreted as a substring indicator.
The third illustrates the escaping of the backslash character. The third illustrates the escaping of the backslash character.
The fourth example shows a filter searching for the four-byte value The fourth example shows a filter searching for the four-byte value
=0C
0x00000004, illustrating the use of the escaping mechanism to represent 0x00000004, illustrating the use of the escaping mechanism to represent
arbitrary data, including NUL characters. arbitrary data, including NUL characters.
The final example illustrates the use of the escaping mechanism to The final example illustrates the use of the escaping mechanism to
represent various non-printing UTF-8 characters. represent various non-ASCII UTF-8 characters.
6. Security Considerations 6. Security Considerations
Security considerations are not discussed in this document. This memo describes a string representation of LDAP search filters.
While the representation itself has no known security implications, LDAP
search filters do. They are interpreted by LDAP servers to select
entries from which data is retrieved. LDAP servers should take care to
protect the data they maintain from unauthorized access.
7. Bibliography 7. References
[1] Lightweight Directory Access Protocol (v3), M. Wahl, T. Howes, S. [1] Lightweight Directory Access Protocol (v3), M. Wahl, T. Howes, S.
Kille, Internet Draft draft-ietf-asid-ldapv3-protocol-04.txt, Kille, Internet Draft draft-ietf-asid-ldapv3-protocol-04.txt,
March, 1997. March, 1997.
[2] Lightweight Directory Access Protocol (v3): Attribute Syntax Defin- [2] Lightweight Directory Access Protocol (v3): Attribute Syntax Defin-
itions, M. Wahl, A. Coulbeck, T. Howes, S. Kille, Internet Draft itions, M. Wahl, A. Coulbeck, T. Howes, S. Kille, Internet Draft
draft-ietf-asid-ldapv3-attributes-04.txt, March, 1997. draft-ietf-asid-ldapv3-attributes-04.txt, March, 1997.
[3] Specification of ASN.1 encoding rules: Basic, Canonical, and Dis- [3] Specification of ASN.1 encoding rules: Basic, Canonical, and Dis-
tinguished Encoding Rules, ITU-T Recommendation X.690, 1994. tinguished Encoding Rules, ITU-T Recommendation X.690, 1994.
[4] Universal Multiple-Octet Coded Character Set (UCS) - Architecture [4] Universal Multiple-Octet Coded Character Set (UCS) - Architecture
and Basic Multilingual Plane, ISO/ IEC 10646-1, 1993. and Basic Multilingual Plane, ISO/ IEC 10646-1, 1993.
[5] Standard for the Format of ARPA Internet Text Messages, D. Crocker,
RFC 822, August, 1982.
8. Author's Address 8. Author's Address
Tim Howes Tim Howes
Netscape Communications Corp. Netscape Communications Corp.
501 E. Middlefield Road 501 E. Middlefield Road
Mountain View, CA 94043 Mountain View, CA 94043
USA USA
+1 415 937-3419 +1 415 937-3419
howes@netscape.com howes@netscape.com
 End of changes. 29 change blocks. 
83 lines changed or deleted 82 lines changed or added

This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/