RFC 2254

The String Representation of LDAP Search Filters

📅 published December 1997, from ietf

RFC 2254: The String Representation of LDAP Search Filters 🎀

Okay bestie, here's the header tea ☕. This is RFC 2254, from the Network Working Group, written by T. Howes of Netscape Communications Corp. It's dated December 1997 and it's on the Standards Track 💖. The header doesn't have an Obsoletes or Updates line, but the Abstract says it replaces RFC 1960 ✨.

1. Status of this Memo ✨

This document is an Internet standards track protocol for the Internet community, and it's openly asking for discussion and suggestions for improvements 💅. For the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1) 📜. Distribution of this memo is unlimited 🦋.

Copyright (C) The Internet Society (1997). All Rights Reserved. 🌸

IESG Note

Okay, this one is super important 🚨. This document describes a directory access protocol with both read and update access. Update access needs secure authentication, but this document does not require any particular satisfactory authentication mechanism 🔐.

The IESG approved this as a Proposed Standard anyway, under RFC 2026 section 4.4.1 🎀. Here's why:

  • a. to encourage implementation and interoperability testing of these protocols (with or without update access) before they are deployed, and
  • b. to encourage deployment and use of these protocols in read-only applications (e.g. applications where LDAPv3 is used as a query language for directories which are updated by some secure mechanism other than LDAP), and
  • c. to avoid delaying the advancement and deployment of other Internet standards-track protocols which require the ability to query, but not update, LDAPv3 directory servers.

Readers, I'm warning you 🙈. Until mandatory authentication mechanisms are standardized, clients and servers written to this specification that use update functionality are UNLIKELY TO INTEROPERATE, or MAY INTEROPERATE ONLY IF AUTHENTICATION IS REDUCED TO AN UNACCEPTABLY WEAK LEVEL 💀.

Implementors are discouraged from deploying LDAPv3 clients or servers that implement the update functionality 🚫. Wait until a Proposed Standard for mandatory authentication in LDAPv3 has been approved and published as an RFC 🫶.

2. Abstract

LDAP (the Lightweight Directory Access Protocol) [1] defines a network representation of a search filter that gets sent to an LDAP server 🧚. Some applications may find it useful to have one common way to write these search filters in a human-readable form 💜. This document defines that human-readable string format for LDAP search filters ✨.

This document replaces RFC 1960 💅. It extends the string LDAP filter definition to support LDAP version 3 extended match filters, and it covers the full range of possible LDAP search filters 👑.

3. LDAP Search Filter Definition

Section 4.5.1 of [1] defines an LDAPv3 search filter like this 🍓:

     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] AttributeDescription,
             approxMatch        [8] AttributeValueAssertion,
             extensibleMatch    [9] MatchingRuleAssertion
     }

     SubstringFilter ::= SEQUENCE {
             type    AttributeDescription,
             SEQUENCE OF CHOICE {
                     initial        [0] LDAPString,
                     any            [1] LDAPString,
                     final          [2] LDAPString
             }
     }

     AttributeValueAssertion ::= SEQUENCE {
             attributeDesc   AttributeDescription,
             attributeValue  AttributeValue
     }

     MatchingRuleAssertion ::= SEQUENCE {
             matchingRule    [1] MatchingRuleID OPTIONAL,
             type            [2] AttributeDescription OPTIONAL,
             matchValue      [3] AssertionValue,
             dnAttributes    [4] BOOLEAN DEFAULT FALSE
     }

     AttributeDescription ::= LDAPString

     AttributeValue ::= OCTET STRING

     MatchingRuleID ::= LDAPString

     AssertionValue ::= OCTET STRING

     LDAPString ::= OCTET STRING

Here the LDAPString is limited to the UTF-8 encoding of the ISO 10646 character set [4] 🌈. The AttributeDescription is a string representation of the attribute description, and it's defined in [1] 💖. The AttributeValue and AssertionValue OCTET STRINGs have the form defined in [2] ✨. The Filter gets encoded for transmission over a network using the Basic Encoding Rules defined in [3], with the simplifications described in [1] 🦋.

4. String Search Filter Definition

Here's the string representation of an LDAP search filter 🎀. It's defined by the grammar below, which follows the ABNF notation from [5] 💅. The filter format uses prefix notation 🔥.

     filter     = "(" filtercomp ")"
     filtercomp = and / or / not / item
     and        = "&" filterlist
     or         = "|" filterlist
     not        = "!" filter
     filterlist = 1*filter
     item       = simple / present / substring / extensible
     simple     = attr filtertype value
     filtertype = equal / approx / greater / less
     equal      = "="
     approx     = "~="
     greater    = ">="
     less       = "<="
     extensible = attr [":dn"] [":" matchingrule] ":=" value
                  / [":dn"] ":" matchingrule ":=" value
     present    = attr "=*"
     substring  = attr "=" [initial] any [final]
     initial    = value
     any        = "*" *(value "*")
     final      = value
     attr       = AttributeDescription from Section 4.1.5 of [1]
     matchingrule = MatchingRuleId from Section 4.1.9 of [1]
     value      = AttributeValue from Section 4.1.6 of [1]

The attr, matchingrule, and value parts work exactly as described in the matching section of [1] given above 🧁.

Now the escaping rules, which are the real main character moment 😭. If a value contains any of these characters:

     Character       ASCII value
     ---------------------------
     *               0x2a
     (               0x28
     )               0x29
     \               0x5c
     NUL             0x00

then that character must be encoded as the backslash '' character (ASCII 0x5c) followed by the two hexadecimal digits representing the ASCII value of the encoded character 🔥. The case of the two hex digits doesn't matter 💜.

This simple escaping mechanism kills filter-parsing ambiguities 💅. It also lets any filter that can be represented in LDAP be represented as a NUL-terminated string 🫶. Other characters besides the ones above may be escaped with this mechanism too, for example non-printing characters 🌸.

For example, a filter checking whether the "cn" attribute contains a value with the "*" character anywhere in it would be written as (cn=*\2a*) ✨.

Note that the substring and present productions in the grammar can both produce the attr=* construct 👀. But this construct is only used to denote a presence filter 🙈.

Copyright (C) The Internet Society (1997). All Rights Reserved. 🎀

okay so the sharing rules are actually pretty generous ✨ You can copy this doc and pass it around to your friends, and you can make derivative works that comment on it, explain it, or help people build with it. You can publish and distribute those too, in whole or in part, with no restriction of any kind 🫶 The one big condition is that the copyright notice and this paragraph have to be included on every single copy and derivative work. Non-negotiable, bestie 😭

The document itself is a different story. You may not modify it in any way, like removing the copyright notice or the references to the Internet Society or other Internet organizations. There are two exceptions. The first is when you need it for developing Internet standards, and then the copyright procedures in the Internet Standards process must be followed. The second is when you need to translate it into a language other than English 🌈

The permissions here are perpetual, and the Internet Society and its successors or assigns won't revoke them. Forever and ever 💅✨

Now the boring-but-important part 🙈 This document and everything in it is provided on an "AS IS" basis, and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. So no promises are being made here, just vibes 🦋💀

📦 where this page comes from