home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_a_c / draft-ietf-asid-ldapv3-filter-01.txt < prev    next >
Text File  |  1997-04-21  |  10KB  |  360 lines
  1.  
  2.  
  3.  
  4.  
  5. Network Working Group                                        Tim Howes
  6. INTERNET DRAFT                            Netscape Communications Corp.
  7. OBSOLETES: RFC 1960                                         April 1997
  8. Expires in six months
  9.  
  10.  
  11.             The String Representation of LDAP Search Filters
  12.                  <draft-ietf-asid-ldapv3-filter-01.txt>
  13.  
  14.  
  15.  
  16. 1.  Status of this Memo
  17.  
  18. This document is an Internet-Draft.  Internet-Drafts are  working  docu-
  19. ments  of the Internet Engineering Task Force (IETF), its areas, and its
  20. working groups.  Note that other  groups  may  also  distribute  working
  21. documents as Internet-Drafts.
  22.  
  23. Internet-Drafts are draft documents valid for a maximum  of  six  months
  24. and  may  be  updated,  replaced, or obsoleted by other documents at any
  25. time.  It is inappropriate to use Internet- Drafts as reference material
  26. or to cite them other than as ``work in progress.''
  27.  
  28. To learn the current status of  any  Internet-Draft,  please  check  the
  29. ``1id-abstracts.txt''  listing  contained in the Internet- Drafts Shadow
  30. Directories on ds.internic.net (US East Coast), nic.nordu.net  (Europe),
  31. ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
  32.  
  33. 2.  Abstract
  34.  
  35. The Lightweight Directory Access Protocol (LDAP) [1] defines  a  network
  36. representation  of  a search filter transmitted to an LDAP server.  Some
  37. applications may find it useful to have a  common  way  of  representing
  38. these  search filters in a human-readable form.  This document defines a
  39. human-readable string format for representing LDAP search filters.
  40.  
  41. This document replaces RFC 1960, extending the string LDAP filter defin-
  42. ition  to include support for LDAP version 3 extended match filters, and
  43. including support for representing  the  full  range  of  possible  LDAP
  44. search filters.
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57. Howes                                                           [Page 1]
  58.  
  59.  
  60.  
  61.  
  62.  
  63. RFC DRAFT                                                     April 1997
  64.  
  65.  
  66. 3.  LDAP Search Filter Definition
  67.  
  68. An LDAPv3 search filter is defined in Section 4.5.1 of [1] as follows:
  69.  
  70.      Filter ::= CHOICE {
  71.              and                [0] SET OF Filter,
  72.              or                 [1] SET OF Filter,
  73.              not                [2] Filter,
  74.              equalityMatch      [3] AttributeValueAssertion,
  75.              substrings         [4] SubstringFilter,
  76.              greaterOrEqual     [5] AttributeValueAssertion,
  77.              lessOrEqual        [6] AttributeValueAssertion,
  78.              present            [7] AttributeDescription,
  79.              approxMatch        [8] AttributeValueAssertion,
  80.              extensibleMatch    [9] MatchingRuleAssertion
  81.      }
  82.  
  83.      SubstringFilter ::= SEQUENCE {
  84.              type    AttributeDescription,
  85.              SEQUENCE OF CHOICE {
  86.                      initial        [0] LDAPString,
  87.                      any            [1] LDAPString,
  88.                      final          [2] LDAPString
  89.              }
  90.      }
  91.  
  92.      AttributeValueAssertion ::= SEQUENCE {
  93.              attributeDesc   AttributeDescription,
  94.              attributeValue  AttributeValue
  95.      }
  96.  
  97.      MatchingRuleAssertion ::= SEQUENCE {
  98.              matchingRule    [1] MatchingRuleID OPTIONAL,
  99.              type            [2] AttributeDescription OPTIONAL,
  100.              matchValue      [3] AssertionValue,
  101.              dnAttributes    [4] BOOLEAN DEFAULT FALSE
  102.      }
  103.  
  104.      AttributeDescription ::= LDAPString
  105.  
  106.      AttributeValue ::= OCTET STRING
  107.  
  108.      MatchingRuleID ::= LDAPString
  109.  
  110.      AssertionValue ::= OCTET STRING
  111.  
  112.      LDAPString ::= OCTET STRING
  113.  
  114.  
  115.  
  116.  
  117. Howes                                                           [Page 2]
  118.  
  119.  
  120.  
  121.  
  122.  
  123. RFC DRAFT                                                     April 1997
  124.  
  125.  
  126. where the LDAPString above is limited to the UTF-8 encoding of  the  ISO
  127. 10646 [4] character set.  The AttributeDescription is a string represen-
  128. tation of the attribute description name and is  defined  in  [1].   The
  129. AttributeValue  and AssertionValue OCTET STRING have the form defined in
  130. [2].  The Filter is encoded for transmission over a  network  using  the
  131. Basic  Encoding  Rules defined in [3], with simplifications described in
  132. [1].
  133.  
  134. 4.  String Search Filter Definition
  135.  
  136. The string representation of an LDAP search filter  is  defined  by  the
  137. following  grammar,  following  the  ABNF  notation defined in [5].  The
  138. filter format uses a prefix notation.
  139.  
  140.      filter     = "(" filtercomp ")"
  141.      filtercomp = and / or / not / item
  142.      and        = "&" filterlist
  143.      or         = "|" filterlist
  144.      not        = "!" filter
  145.      filterlist = 1*filter
  146.      item       = simple / present / substring / extensible
  147.      simple     = attr filtertype value
  148.      filtertype = equal / approx / greater / less
  149.      equal      = "="
  150.      approx     = "~="
  151.      greater    = ">="
  152.      less       = "<="
  153.      extensible = attr [":dn"] [":" matchingrule] ":=" value
  154.                   / [":dn"] ":" matchingrule ":=" value
  155.      present    = attr "=*"
  156.      substring  = attr "=" [initial] any [final]
  157.      initial    = value
  158.      any        = "*" *(value "*")
  159.      final      = value
  160.      attr       = AttributeDescription from Section 4.1.5 of [1]
  161.      matchingrule = MatchingRuleId from Section 4.1.9 of [1]
  162.      value      = AttributeValue from Section 4.1.6 of [1]
  163.  
  164. The attr, matchingrule, and value constructs are  as  described  in  the
  165. corresponding section of [1] given above.
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177. Howes                                                           [Page 3]
  178.  
  179.  
  180.  
  181.  
  182.  
  183. RFC DRAFT                                                     April 1997
  184.  
  185.  
  186. If a value should contain any of the following characters
  187.  
  188.         Character       ASCII value
  189.         ---------------------------
  190.         *               0x2a
  191.         (               0x28
  192.         )               0x29
  193.         \               0x5c
  194.         NUL             0x00
  195.  
  196. the character must be encoded as the backslash '\' character followed by
  197. the  two  hexadecimal digits representing the ASCII value of the encoded
  198. character.
  199.  
  200. This simple escaping mechanism eliminates filter-parsing ambiguities and
  201. allows any filter that can be represented in LDAP to be represented as a
  202. NUL-terminated string.  The case of the two hexadecimal  digits  is  not
  203. significant.  Other  characters  besides  the  ones  listed above may be
  204. escaped using this mechanism, for example, non-printing characters.
  205.  
  206. For example, the filter checking whether the "cn" attribute contained  a
  207. value  with  the  character  "*"  anywhere in it would be represented as
  208. "(cn=*\2a*)".
  209.  
  210. Note that although both the substring and  present  productions  in  the
  211. grammar above can produce the "attr=*" construct, this construct is used
  212. only to denote a presence filter.
  213.  
  214. 5.  Examples
  215.  
  216. This section gives a few examples of search filters written  using  this
  217. notation.
  218.  
  219.      (cn=Babs Jensen)
  220.      (!(cn=Tim Howes))
  221.      (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
  222.      (o=univ*of*mich*)
  223.  
  224. The following examples illustrate the use of extensible matching.
  225.  
  226.      (cn:1.2.3.4.5:=Fred Flintstone)
  227.      (sn:dn:2.4.6.8.10:=Barney Rubble)
  228.      (o:dn:=Ace Industry)
  229.  
  230. The second example illustrates the use of the ":dn" notation to indicate
  231. that  matching rule "2.4.6.8.10" should be used when making comparisons,
  232. and that the attributes of an entry's distinguished name should be  con-
  233. sidered part of the entry when evaluating the match.
  234.  
  235.  
  236.  
  237. Howes                                                           [Page 4]
  238.  
  239.  
  240.  
  241.  
  242.  
  243. RFC DRAFT                                                     April 1997
  244.  
  245.  
  246. The third example denotes an equality match, except that  DN  components
  247. should be considered part of the entry when doing the match.
  248.  
  249. The following examples illustrate the use of the escaping mechanism.
  250.  
  251.      (o=Parens R Us \28for all your parenthetical needs\29)
  252.      (cn=*\2A*)
  253.      (filename=C:\5cMyFile)
  254.      (bin=\00\00\00\04)
  255.      (sn=Lu\c4\8di\c4\c7)
  256.  
  257. The first example shows the use of the escaping mechanism  to  represent
  258. parenthesis  characters.  The  second  shows how to represent a "*" in a
  259. value, preventing it from being interpreted as  a  substring  indicator.
  260. The third illustrates the escaping of the backslash character.
  261.  
  262. The fourth example shows a filter  searching  for  the  four-byte  value
  263. 0x00000004,  illustrating the use of the escaping mechanism to represent
  264. arbitrary data, including NUL characters.
  265.  
  266. The final example illustrates the  use  of  the  escaping  mechanism  to
  267. represent various non-ASCII UTF-8 characters.
  268.  
  269. 6.  Security Considerations
  270.  
  271. This memo describes a string  representation  of  LDAP  search  filters.
  272. While the representation itself has no known security implications, LDAP
  273. search filters do. They  are  interpreted  by  LDAP  servers  to  select
  274. entries  from which data is retrieved.  LDAP servers should take care to
  275. protect the data they maintain from unauthorized access.
  276.  
  277. 7.  References
  278.  
  279. [1]  Lightweight Directory Access Protocol (v3), M. Wahl, T.  Howes,  S.
  280.      Kille,   Internet   Draft   draft-ietf-asid-ldapv3-protocol-04.txt,
  281.      March, 1997.
  282.  
  283. [2]  Lightweight Directory Access Protocol (v3): Attribute Syntax Defin-
  284.      itions,  M.  Wahl,  A. Coulbeck, T. Howes, S. Kille, Internet Draft
  285.      draft-ietf-asid-ldapv3-attributes-04.txt, March, 1997.
  286.  
  287. [3]  Specification of ASN.1 encoding rules: Basic, Canonical,  and  Dis-
  288.      tinguished Encoding Rules, ITU-T Recommendation X.690, 1994.
  289.  
  290. [4]  Universal Multiple-Octet Coded Character Set (UCS)  -  Architecture
  291.      and Basic Multilingual Plane, ISO/ IEC 10646-1, 1993.
  292.  
  293. [5]  Standard for the Format of ARPA Internet Text Messages, D. Crocker,
  294.  
  295.  
  296.  
  297. Howes                                                           [Page 5]
  298.  
  299.  
  300.  
  301.  
  302.  
  303. RFC DRAFT                                                     April 1997
  304.  
  305.  
  306.      RFC 822, August, 1982.
  307.  
  308. 8.  Author's Address
  309.  
  310.    Tim Howes
  311.    Netscape Communications Corp.
  312.    501 E. Middlefield Road
  313.    Mountain View, CA 94043
  314.    USA
  315.    +1 415 937-3419
  316.    howes@netscape.com
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357. Howes                                                           [Page 6]
  358.  
  359.  
  360.