3. String Search Filter Definition

The string representation of an LDAP search filter is a string of UTF-8 [RFC3629] encoded Unicode characters [Unicode] that is defined by the following grammar, following the ABNF notation defined in [RFC4234]. The productions used that are not defined here are defined in Section 1.4 (Common ABNF Productions) of [RFC4512] unless otherwise noted. The filter format uses a prefix notation.

  filter         = LPAREN filtercomp RPAREN
  filtercomp     = and / or / not / item
  and            = AMPERSAND filterlist
  or             = VERTBAR filterlist
  not            = EXCLAMATION filter
  filterlist     = 1*filter
  item           = simple / present / substring / extensible
  simple         = attr filtertype assertionvalue
  filtertype     = equal / approx / greaterorequal / lessorequal






  equal          = EQUALS
  approx         = TILDE EQUALS
  greaterorequal = RANGLE EQUALS
  lessorequal    = LANGLE EQUALS
  extensible     = ( attr [dnattrs]
                       [matchingrule] COLON EQUALS assertionvalue )
                   / ( [dnattrs]
                        matchingrule COLON EQUALS assertionvalue )
  present        = attr EQUALS ASTERISK
  substring      = attr EQUALS [initial] any [final]
  initial        = assertionvalue
  any            = ASTERISK *(assertionvalue ASTERISK)
  final          = assertionvalue
  attr           = attributedescription
                     ; The attributedescription rule is defined in
                     ; Section 2.5 of [RFC4512].
  dnattrs        = COLON "dn"
  matchingrule   = COLON oid
  assertionvalue = valueencoding
  ; The <valueencoding> rule is used to encode an <AssertionValue>
  ; from Section 4.1.6 of [RFC4511].
  valueencoding  = 0*(normal / escaped)
  normal         = UTF1SUBSET / UTFMB
  escaped        = ESC HEX HEX
  UTF1SUBSET     = %x01-27 / %x2B-5B / %x5D-7F
                      ; UTF1SUBSET excludes 0x00 (NUL), LPAREN,
                      ; RPAREN, ASTERISK, and ESC.
  EXCLAMATION    = %x21 ; exclamation mark ("!")
  AMPERSAND      = %x26 ; ampersand (or AND symbol) ("&")
  ASTERISK       = %x2A ; asterisk ("*")
  COLON          = %x3A ; colon (":")
  VERTBAR        = %x7C ; vertical bar (or pipe) ("|")
  TILDE          = %x7E ; tilde ("~")

Note that although both the and productions in the grammar above can produce the "attr=*" construct, this construct is used only to denote a presence filter.

The rule ensures that the entire filter string is a valid UTF-8 string and provides that the octets that represent the ASCII characters "*" (ASCII 0x2a), "(" (ASCII 0x28), ")" (ASCII 0x29), "" (ASCII 0x5c), and NUL (ASCII 0x00) are represented as a backslash "" (ASCII 0x5c) followed by the two hexadecimal digits representing the value of the encoded octet.

This simple escaping mechanism eliminates filter-parsing ambiguities and allows any filter that can be represented in LDAP to be represented as a NUL-terminated string. Other octets that are part of the set may be escaped using this mechanism, for example, non-printing ASCII characters.

For AssertionValues that contain UTF-8 character data, each octet of the character to be escaped is replaced by a backslash and two hex digits, which form a single octet in the code of the character. For example, the filter checking whether the "cn" attribute contained a value with the character "" anywhere in it would be represented as "(cn=\2a*)".

As indicated by the rule, implementations MUST escape all octets greater than 0x7F that are not part of a valid UTF-8 encoding sequence when they generate a string representation of a search filter. Implementations SHOULD accept as input strings that are not valid UTF-8 strings. This is necessary because RFC 2254 did not clearly define the term "string representation" (and in particular did not mention that the string representation of an LDAP search filter is a string of UTF-8-encoded Unicode characters).