git.sur5r.net Git - openldap/blob - 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