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