RFC 1558

RFC 1558: A String Representation of LDAP Search Filters 💖

okay so bestie, this is RFC 1558 from the Network Working Group 🎀 It's written by T. Howes (that's Tim Howes, at the University of Michigan), it's Category: Informational, and it's dated December 1993 🦋 The header doesn't list anything it obsoletes or updates, so it's not replacing or changing any other RFC 🫶

Status of this Memo ✨

okay this part is the legal-ish bit, but it's lowkey important 📖 This memo provides information for the Internet community. It does not specify an Internet standard of any kind 🙈 And distribution of this memo is unlimited 🌈

Abstract 🌸

so LDAP (the Lightweight Directory Access Protocol) [1] defines a network representation of a search filter that gets sent to an LDAP server 🧚 Some applications might find it useful to have one common, human-readable way of writing these search filters, and that's exactly what this doc defines ✨

1. LDAP Search Filter Definition 💅

okay here's how [1] defines an LDAP search filter, and it's giving CHOICE energy 💜

     Filter ::= CHOICE {
             and                [0] SET OF Filter,
             or                 [1] SET OF Filter,
             not                [2] Filter,
             equalityMatch      [3] AttributeValueAssertion,
             substrings         [4] SubstringFilter,
             greaterOrEqual     [5] AttributeValueAssertion,
             lessOrEqual        [6] AttributeValueAssertion,
             present            [7] AttributeType,
             approxMatch        [8] AttributeValueAssertion
     }

     SubstringFilter ::= SEQUENCE {
             type    AttributeType,
             SEQUENCE OF CHOICE {
                     initial        [0] LDAPString,
                     any            [1] LDAPString,
                     final          [2] LDAPString
             }
     }
     AttributeValueAssertion ::= SEQUENCE
             attributeType   AttributeType,
             attributeValue  AttributeValue
     }

     AttributeType ::= LDAPString

     AttributeValue ::= OCTET STRING

     LDAPString ::= OCTET STRING

the LDAPString up there is limited to the IA5 character set 🔥 The AttributeType is a string representation of the attribute object identifier in dotted OID format (e.g., "2.5.4.10"), or the shorter string name of the attribute (e.g., "organizationName", or "o"). The AttributeValue OCTET STRING has the form defined in [2]. The Filter is encoded for transmission over a network using the Basic Encoding Rules defined in [3], with simplifications described in [1] 🫧

2. String Search Filter Definition 👑

the string version is defined by the BNF below, and it uses a prefix format 💜

     <filter> ::= '(' <filtercomp> ')'
     <filtercomp> ::= <and> | <or> | <not> | <item>
     <and> ::= '&' <filterlist>
     <or> ::= '|' <filterlist>
     <not> ::= '!' <filter>
     <filterlist> ::= <filter> | <filter> <filterlist>
     <item> ::= <simple> | <present> | <substring>
     <simple> ::= <attr> <filtertype> <value>
     <filtertype> ::= <equal> | <approx> | <greater> | <less>
     <equal> ::= '='
     <approx> ::= '~='
     <greater> ::= '>='
     <less> ::= '<='
     <present> ::= <attr> '=*'
     <substring> ::= <attr> '=' <initial> <any> <final>
     <initial> ::= NULL | <value>
     <any> ::= '*' <starval>
     <starval> ::= NULL | <value> '*' <starval>
     <final> ::= NULL | <value>

<attr> is a string representing an AttributeType, and it has the format defined in [1]. <value> is a string representing an AttributeValue, or part of one, and it has the form defined in [2]. If a <value> must contain one of the characters '*' or '(' or ')', these characters should be escaped by preceding them with the backslash '\' character 🙈

3. Examples 🍓

this section gives a few examples of search filters written using this notation 🧚

     (cn=Babs Jensen)
     (!(cn=Tim Howes))
     (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*)))
     (o=univ*of*mich*)

4. Security Considerations 💀

plot twist: security issues are not discussed in this memo. Literally nothing on it 💀 Security issues are not discussed in this memo, full stop.

5. References 📚

[1] Yeong, W., Howes, T., and S. Kille, "Lightweight Directory Access Protocol", RFC 1487, Performance Systems International, University of Michigan, ISODE Consortium, July 1993.

[2] Howes, T., Kille, S., Yeong, W., and C. Robbins, "The String Representation of Standard Attribute Syntaxes", RFC 1488, University of Michigan, ISODE Consortium, Performance Systems International, NeXor Ltd., July 1993.

[3] "Specification of Basic Encoding Rules for Abstract Syntax Notation One (ASN.1)", CCITT Recommendation X.209, 1988.

6. Author's Address 🦋

     Tim Howes
     University of Michigan
     ITD Research Systems
     535 W William St.
     Ann Arbor, MI 48103-4943
     USA

     Phone: +1 313 747-4454
     EMail: tim@umich.edu