]> git.sur5r.net Git - openldap/blob - doc/rfc/rfc2254.txt
Sync with HEAD
[openldap] / doc / rfc / rfc2254.txt
1
2
3
4
5
6
7 Network Working Group                                          T. Howes
8 Request for Comments: 2254                Netscape Communications Corp.
9 Category: Standards Track                                 December 1997
10
11
12             The String Representation of LDAP Search Filters
13
14 1. Status of this Memo
15
16    This document specifies an Internet standards track protocol for the
17    Internet community, and requests discussion and suggestions for
18    improvements.  Please refer to the current edition of the "Internet
19    Official Protocol Standards" (STD 1) for the standardization state
20    and status of this protocol.  Distribution of this memo is unlimited.
21
22 Copyright Notice
23
24    Copyright (C) The Internet Society (1997).  All Rights Reserved.
25
26 IESG Note
27
28    This document describes a directory access protocol that provides
29    both read and update access.  Update access requires secure
30    authentication, but this document does not mandate implementation of
31    any satisfactory authentication mechanisms.
32
33    In accordance with RFC 2026, section 4.4.1, this specification is
34    being approved by IESG as a Proposed Standard despite this
35    limitation, for the following reasons:
36
37    a. to encourage implementation and interoperability testing of
38       these protocols (with or without update access) before they
39       are deployed, and
40
41    b. to encourage deployment and use of these protocols in read-only
42       applications.  (e.g. applications where LDAPv3 is used as
43       a query language for directories which are updated by some
44       secure mechanism other than LDAP), and
45
46    c. to avoid delaying the advancement and deployment of other Internet
47       standards-track protocols which require the ability to query, but
48       not update, LDAPv3 directory servers.
49
50
51
52
53
54
55
56
57
58 Howes                       Standards Track                     [Page 1]
59 \f
60 RFC 2254             String Representation of LDAP         December 1997
61
62
63    Readers are hereby warned that until mandatory authentication
64    mechanisms are standardized, clients and servers written according to
65    this specification which make use of update functionality are
66    UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION
67    IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL.
68
69    Implementors are hereby discouraged from deploying LDAPv3 clients or
70    servers which implement the update functionality, until a Proposed
71    Standard for mandatory authentication in LDAPv3 has been approved and
72    published as an RFC.
73
74 2. Abstract
75
76    The Lightweight Directory Access Protocol (LDAP) [1] defines a
77    network representation of a search filter transmitted to an LDAP
78    server.  Some applications may find it useful to have a common way of
79    representing these search filters in a human-readable form.  This
80    document defines a human-readable string format for representing LDAP
81    search filters.
82
83    This document replaces RFC 1960, extending the string LDAP filter
84    definition to include support for LDAP version 3 extended match
85    filters, and including support for representing the full range of
86    possible LDAP search filters.
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114 Howes                       Standards Track                     [Page 2]
115 \f
116 RFC 2254             String Representation of LDAP         December 1997
117
118
119 3. LDAP Search Filter Definition
120
121    An LDAPv3 search filter is defined in Section 4.5.1 of [1] as
122    follows:
123
124         Filter ::= CHOICE {
125                 and                [0] SET OF Filter,
126                 or                 [1] SET OF Filter,
127                 not                [2] Filter,
128                 equalityMatch      [3] AttributeValueAssertion,
129                 substrings         [4] SubstringFilter,
130                 greaterOrEqual     [5] AttributeValueAssertion,
131                 lessOrEqual        [6] AttributeValueAssertion,
132                 present            [7] AttributeDescription,
133                 approxMatch        [8] AttributeValueAssertion,
134                 extensibleMatch    [9] MatchingRuleAssertion
135         }
136
137         SubstringFilter ::= SEQUENCE {
138                 type    AttributeDescription,
139                 SEQUENCE OF CHOICE {
140                         initial        [0] LDAPString,
141                         any            [1] LDAPString,
142                         final          [2] LDAPString
143                 }
144         }
145
146         AttributeValueAssertion ::= SEQUENCE {
147                 attributeDesc   AttributeDescription,
148                 attributeValue  AttributeValue
149         }
150
151         MatchingRuleAssertion ::= SEQUENCE {
152                 matchingRule    [1] MatchingRuleID OPTIONAL,
153                 type            [2] AttributeDescription OPTIONAL,
154                 matchValue      [3] AssertionValue,
155                 dnAttributes    [4] BOOLEAN DEFAULT FALSE
156         }
157
158         AttributeDescription ::= LDAPString
159
160         AttributeValue ::= OCTET STRING
161
162         MatchingRuleID ::= LDAPString
163
164         AssertionValue ::= OCTET STRING
165
166         LDAPString ::= OCTET STRING
167
168
169
170 Howes                       Standards Track                     [Page 3]
171 \f
172 RFC 2254             String Representation of LDAP         December 1997
173
174
175    where the LDAPString above is limited to the UTF-8 encoding of the
176    ISO 10646 character set [4].  The AttributeDescription is a string
177    representation of the attribute description and is defined in [1].
178    The AttributeValue and AssertionValue OCTET STRING have the form
179    defined in [2].  The Filter is encoded for transmission over a
180    network using the Basic Encoding Rules defined in [3], with
181    simplifications described in [1].
182
183 4. String Search Filter Definition
184
185    The string representation of an LDAP search filter is defined by the
186    following grammar, following the ABNF notation defined in [5].  The
187    filter format uses a prefix notation.
188
189         filter     = "(" filtercomp ")"
190         filtercomp = and / or / not / item
191         and        = "&" filterlist
192         or         = "|" filterlist
193         not        = "!" filter
194         filterlist = 1*filter
195         item       = simple / present / substring / extensible
196         simple     = attr filtertype value
197         filtertype = equal / approx / greater / less
198         equal      = "="
199         approx     = "~="
200         greater    = ">="
201         less       = "<="
202         extensible = attr [":dn"] [":" matchingrule] ":=" value
203                      / [":dn"] ":" matchingrule ":=" value
204         present    = attr "=*"
205         substring  = attr "=" [initial] any [final]
206         initial    = value
207         any        = "*" *(value "*")
208         final      = value
209         attr       = AttributeDescription from Section 4.1.5 of [1]
210         matchingrule = MatchingRuleId from Section 4.1.9 of [1]
211         value      = AttributeValue from Section 4.1.6 of [1]
212
213    The attr, matchingrule, and value constructs are as described in the
214    corresponding section of [1] given above.
215
216
217
218
219
220
221
222
223
224
225
226 Howes                       Standards Track                     [Page 4]
227 \f
228 RFC 2254             String Representation of LDAP         December 1997
229
230
231    If a value should contain any of the following characters
232
233            Character       ASCII value
234            ---------------------------
235            *               0x2a
236            (               0x28
237            )               0x29
238            \               0x5c
239            NUL             0x00
240
241    the character must be encoded as the backslash '\' character (ASCII
242    0x5c) followed by the two hexadecimal digits representing the ASCII
243    value of the encoded character. The case of the two hexadecimal
244    digits is not significant.
245
246    This simple escaping mechanism eliminates filter-parsing ambiguities
247    and allows any filter that can be represented in LDAP to be
248    represented as a NUL-terminated string. Other characters besides the
249    ones listed above may be escaped using this mechanism, for example,
250    non-printing characters.
251
252    For example, the filter checking whether the "cn" attribute contained
253    a value with the character "*" anywhere in it would be represented as
254    "(cn=*\2a*)".
255
256    Note that although both the substring and present productions in the
257    grammar above can produce the "attr=*" construct, this construct is
258    used only to denote a presence filter.
259
260 5. Examples
261
262    This section gives a few examples of search filters written using
263    this notation.
264
265         (cn=Babs Jensen)
266         (!(cn=Tim Howes))
267         (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
268         (o=univ*of*mich*)
269
270    The following examples illustrate the use of extensible matching.
271
272         (cn:1.2.3.4.5:=Fred Flintstone)
273         (sn:dn:2.4.6.8.10:=Barney Rubble)
274         (o:dn:=Ace Industry)
275         (:dn:2.4.6.8.10:=Dino)
276
277
278
279
280
281
282 Howes                       Standards Track                     [Page 5]
283 \f
284 RFC 2254             String Representation of LDAP         December 1997
285
286
287    The second example illustrates the use of the ":dn" notation to
288    indicate that matching rule "2.4.6.8.10" should be used when making
289    comparisons, and that the attributes of an entry's distinguished name
290    should be considered part of the entry when evaluating the match.
291
292    The third example denotes an equality match, except that DN
293    components should be considered part of the entry when doing the
294    match.
295
296    The fourth example is a filter that should be applied to any
297    attribute supporting the matching rule given (since the attr has been
298    left off). Attributes supporting the matching rule contained in the
299    DN should also be considered.
300
301    The following examples illustrate the use of the escaping mechanism.
302
303         (o=Parens R Us \28for all your parenthetical needs\29)
304         (cn=*\2A*)
305         (filename=C:\5cMyFile)
306         (bin=\00\00\00\04)
307         (sn=Lu\c4\8di\c4\87)
308
309    The first example shows the use of the escaping mechanism to
310    represent parenthesis characters. The second shows how to represent a
311    "*" in a value, preventing it from being interpreted as a substring
312    indicator. The third illustrates the escaping of the backslash
313    character.
314
315    The fourth example shows a filter searching for the four-byte value
316    0x00000004, illustrating the use of the escaping mechanism to
317    represent arbitrary data, including NUL characters.
318
319    The final example illustrates the use of the escaping mechanism to
320    represent various non-ASCII UTF-8 characters.
321
322 6. Security Considerations
323
324    This memo describes a string representation of LDAP search filters.
325    While the representation itself has no known security implications,
326    LDAP search filters do. They are interpreted by LDAP servers to
327    select entries from which data is retrieved.  LDAP servers should
328    take care to protect the data they maintain from unauthorized access.
329
330
331
332
333
334
335
336
337
338 Howes                       Standards Track                     [Page 6]
339 \f
340 RFC 2254             String Representation of LDAP         December 1997
341
342
343 7. References
344
345    [1] Wahl, M., Howes, T., and S. Kille, "Lightweight Directory Access
346    Protocol (v3)", RFC 2251, December 1997.
347
348    [2] Wahl, M., Coulbeck, A., Howes, T., and S. Kille, "Lightweight
349    Directory Access Protocol (v3): Attribute Syntax Definitions", RFC
350    2252, December 1997.
351
352    [3] Specification of ASN.1 encoding rules: Basic, Canonical, and
353    Distinguished Encoding Rules, ITU-T Recommendation X.690, 1994.
354
355    [4] Yergeau, F., "UTF-8, a transformation format of Unicode and ISO
356    10646", RFC 2044, October 1996.
357
358    [5] Crocker, D., "Standard for the Format of ARPA Internet Text
359    Messages", STD 11, RFC 822, August 1982.
360
361 8. Author's Address
362
363    Tim Howes
364    Netscape Communications Corp.
365    501 E. Middlefield Road
366    Mountain View, CA 94043
367    USA
368
369    Phone: +1 415 937-3419
370    EMail: howes@netscape.com
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394 Howes                       Standards Track                     [Page 7]
395 \f
396 RFC 2254             String Representation of LDAP         December 1997
397
398
399 9. Full Copyright Statement
400
401    Copyright (C) The Internet Society (1997).  All Rights Reserved.
402
403    This document and translations of it may be copied and furnished to
404    others, and derivative works that comment on or otherwise explain it
405    or assist in its implementation may be prepared, copied, published
406    and distributed, in whole or in part, without restriction of any
407    kind, provided that the above copyright notice and this paragraph are
408    included on all such copies and derivative works.  However, this
409    document itself may not be modified in any way, such as by removing
410    the copyright notice or references to the Internet Society or other
411    Internet organizations, except as needed for the purpose of
412    developing Internet standards in which case the procedures for
413    copyrights defined in the Internet Standards process must be
414    followed, or as required to translate it into languages other than
415    English.
416
417    The limited permissions granted above are perpetual and will not be
418    revoked by the Internet Society or its successors or assigns.
419
420    This document and the information contained herein is provided on an
421    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
422    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
423    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
424    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
425    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450 Howes                       Standards Track                     [Page 8]
451 \f