git.sur5r.net Git - openldap/blob - doc/rfc/rfc1960.txt

   1 \r
   2 \r
   3 \r
   4 \r
   5 \r
   6 \r
   7 Network Working Group                                           T. Howes\r
   8 Request for Comments: 1960                        University of Michigan\r
   9 Obsoletes: 1558                                                June 1996\r
  10 Category: Standards Track\r
  11 \r
  12              A String Representation of LDAP Search Filters\r
  13 \r
  14 Status of this Memo\r
  15 \r
  16    This document specifies an Internet standards track protocol for the\r
  17    Internet community, and requests discussion and suggestions for\r
  18    improvements.  Please refer to the current edition of the "Internet\r
  19    Official Protocol Standards" (STD 1) for the standardization state\r
  20    and status of this protocol.  Distribution of this memo is unlimited.\r
  21 \r
  22 1.  Abstract\r
  23 \r
  24    The Lightweight Directory Access Protocol (LDAP) [1] defines a\r
  25    network representation of a search filter transmitted to an LDAP\r
  26    server.  Some applications may find it useful to have a common way of\r
  27    representing these search filters in a human-readable form.  This\r
  28    document defines a human-readable string format for representing LDAP\r
  29    search filters.\r
  30 \r
  31 2.  LDAP Search Filter Definition\r
  32 \r
  33    An LDAP search filter is defined in [1] as follows:\r
  34 \r
  35      Filter ::= CHOICE {\r
  36              and                [0] SET OF Filter,\r
  37              or                 [1] SET OF Filter,\r
  38              not                [2] Filter,\r
  39              equalityMatch      [3] AttributeValueAssertion,\r
  40              substrings         [4] SubstringFilter,\r
  41              greaterOrEqual     [5] AttributeValueAssertion,\r
  42              lessOrEqual        [6] AttributeValueAssertion,\r
  43              present            [7] AttributeType,\r
  44              approxMatch        [8] AttributeValueAssertion\r
  45      }\r
  46 \r
  47      SubstringFilter ::= SEQUENCE {\r
  48              type    AttributeType,\r
  49              SEQUENCE OF CHOICE {\r
  50                      initial        [0] LDAPString,\r
  51                      any            [1] LDAPString,\r
  52                      final          [2] LDAPString\r
  53              }\r
  54      }\r
  55 \r
  56 \r
  57 \r
  58 Howes                       Standards Track                     [Page 1]\r
  59 \f\r
  60 RFC 1960                  LDAP Search Filters                  June 1996\r
  61 \r
  62 \r
  63      AttributeValueAssertion ::= SEQUENCE {\r
  64              attributeType   AttributeType,\r
  65              attributeValue  AttributeValue\r
  66      }\r
  67 \r
  68      AttributeType ::= LDAPString\r
  69 \r
  70      AttributeValue ::= OCTET STRING\r
  71 \r
  72      LDAPString ::= OCTET STRING\r
  73 \r
  74    where the LDAPString above is limited to the IA5 character set.  The\r
  75    AttributeType is a string representation of the attribute type name\r
  76    and is defined in [1].  The AttributeValue OCTET STRING has the form\r
  77    defined in [2].  The Filter is encoded for transmission over a\r
  78    network using the Basic Encoding Rules defined in [3], with\r
  79    simplifications described in [1].\r
  80 \r
  81 3.  String Search Filter Definition\r
  82 \r
  83    The string representation of an LDAP search filter is defined by the\r
  84    following grammar.  It uses a prefix format.\r
  85 \r
  86      <filter> ::= '(' <filtercomp> ')'\r
  87      <filtercomp> ::= <and> | <or> | <not> | <item>\r
  88      <and> ::= '&' <filterlist>\r
  89      <or> ::= '|' <filterlist>\r
  90      <not> ::= '!' <filter>\r
  91      <filterlist> ::= <filter> | <filter> <filterlist>\r
  92      <item> ::= <simple> | <present> | <substring>\r
  93      <simple> ::= <attr> <filtertype> <value>\r
  94      <filtertype> ::= <equal> | <approx> | <greater> | <less>\r
  95      <equal> ::= '='\r
  96      <approx> ::= '~='\r
  97      <greater> ::= '>='\r
  98      <less> ::= '<='\r
  99      <present> ::= <attr> '=*'\r
 100      <substring> ::= <attr> '=' <initial> <any> <final>\r
 101      <initial> ::= NULL | <value>\r
 102      <any> ::= '*' <starval>\r
 103      <starval> ::= NULL | <value> '*' <starval>\r
 104      <final> ::= NULL | <value>\r
 105 \r
 106    <attr> is a string representing an AttributeType, and has the format\r
 107    defined in [1].  <value> is a string representing an AttributeValue,\r
 108    or part of one, and has the form defined in [2].  If a <value> must\r
 109    contain one of the characters '*' or '(' or ')', these characters\r
 110    should be escaped by preceding them with the backslash '\' character.\r
 111 \r
 112 \r
 113 \r
 114 Howes                       Standards Track                     [Page 2]\r
 115 \f\r
 116 RFC 1960                  LDAP Search Filters                  June 1996\r
 117 \r
 118 \r
 119    Note that although both the <substring> and <present> productions can\r
 120    produce the 'attr=*' construct, this construct is used only to denote\r
 121    a presence filter.\r
 122 \r
 123 4.  Examples\r
 124 \r
 125    This section gives a few examples of search filters written using\r
 126    this notation.\r
 127 \r
 128      (cn=Babs Jensen)\r
 129      (!(cn=Tim Howes))\r
 130      (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))\r
 131      (o=univ*of*mich*)\r
 132 \r
 133 5.  Security Considerations\r
 134 \r
 135    Security considerations are not discussed in this memo.\r
 136 \r
 137 6.  Bibliography\r
 138 \r
 139    [1] Yeong, W., Howes, T., and S. Kille, "Lightweight\r
 140        Directory Access Protocol", RFC 1777, March 1995.\r
 141 \r
 142    [2] Howes, R., Kille, S., Yeong, W., and C. Robbins, "The String\r
 143        Representation of Standard Attribute Syntaxes", RFC 1778,\r
 144        March 1995.\r
 145 \r
 146    [3] Specification of Basic Encoding Rules for Abstract Syntax\r
 147        Notation One (ASN.1).  CCITT Recommendation X.209, 1988.\r
 148 \r
 149 7.  Author's Address\r
 150 \r
 151    Tim Howes\r
 152    University of Michigan\r
 153    ITD Research Systems\r
 154    535 W William St.\r
 155    Ann Arbor, MI 48103-4943\r
 156    USA\r
 157 \r
 158    Phone: +1 313 747-4454\r
 159    EMail: tim@umich.edu\r
 160 \r
 161 \r
 162 \r
 163 \r
 164 \r
 165 \r
 166 \r
 167 \r
 168 \r
 169 \r
 170 Howes                       Standards Track                     [Page 3]\r
 171 \f\r