LDAP Equality, Presence, and Substring Filters

LDAP directories are queried using search filters—expressions that determine which entries a server returns in response to a search operation. Among several types defined by the Lightweight Directory Access Protocol (LDAP), equality, presence, and substring filters form the foundation of nearly all directory queries. A solid grasp of each filter’s intent, syntax, operational differences, and schema interactions is essential for anyone implementing or troubleshooting LDAP-integrated systems.

LDAP Search Filters: The Foundation

LDAP search filters encapsulate the logic used to match directory entries based on their attributes and values. Defined formally in RFC 4515 and utilized in all LDAP protocol operations (RFC 4511), filters allow complex queries by combining logical and attribute-specific conditions. Equality, presence, and substring filters underpin this system:

• Equality filters match exact values of attributes.
• Presence filters test for the existence of an attribute, regardless of its value.
• Substring filters enable partial matching on string attributes using wildcards.

Mastering these primitives is critical: complex queries are built on these building blocks, and selecting the right filter impacts both correctness and directory performance.

LDAP Presence Filters: Syntax and Use

A presence filter searches for entries where a given attribute is present, with any value. Its canonical syntax, specified in RFC 4515, is:

(attribute=*)

Here, attribute names the attribute of interest, and the asterisk * is not a wildcard but a required presence indicator. This filter will match any entry where attribute exists and has at least one value. For example, (mail=*) returns all entries with a mail attribute, regardless of its content.

Key points:

• (attribute=*) is always a presence filter, not a substring filter. It never evaluates the value, only existence.
• No other meaning for *: In this context, * merely signals presence; it does not function as a wildcard for partial matching.
• Schema impact: Presence filters are valid for all attribute types (string, integer, etc.).

This distinction is crucial—confusing presence with substring (wildcard) leads to logic and performance errors.

LDAP Equality Filters: Exact Match Logic

An equality filter matches entries where an attribute's value exactly equals the provided value, following the attribute's defined equality matching rule. Its formal syntax is:

(attribute=value)

For example, (cn=John Doe) returns entries with a cn (common name) exactly equal to "John Doe" as determined by the attribute's matching rules.

Semantic details:

• Case sensitivity and value normalization depend on the attribute's schema and defined matching rule. For instance, string attributes may be matched case-insensitively, while others (like some binary or numeric types) are case-sensitive.
• Matching rule enforcement: The schema may adjust comparison (e.g., trimming whitespace, collapsing case, normalizing encoding).
• Efficiency: Equality filters are typically highly performant and make use of directory indexes where available.

LDAP Substring Filters: Partial Match Logic

Substring filters enable partial matching on string attributes, using the * character as a wildcard representing any sequence of zero or more characters. The syntax is:

(attribute=initial*any*final)

• initial (optional): Matches the beginning of the value.
• any (optional, may be repeated): Matches substrings in the middle.
• final (optional): Matches the end.

Examples:

• (cn=John*) matches entries whose cn begins with "John".
• (mail=*example.com) matches entries with an email address ending in "example.com".
• (sn=*son) finds surnames ending in "son".
• (cn=Jo*nn*Doe*) matches values where "Jo", "nn", and "Doe" appear in order.

Syntax rules:

• At least one * must appear in the filter value for it to be a substring filter.
• Substring filters are only defined for string-based attributes; using them on non-string types (like integers or binary data) is not standardized and may be unsupported.

Performance caveats:

• Trailing wildcards (foo*) can benefit from directory indexes.
• Leading wildcards (*bar) usually cannot be indexed, often causing full attribute scans and poor performance on large directories.

Choosing the Right Filter: Comparisons and Tradeoffs

The filter type directly affects both query results and performance.

• Equality filters are preferred when searching for exact known values. Directories can normally leverage indexes for fast, efficient lookups.
• Presence filters are ideal when the existence (not the value) of an attribute is sufficient, such as finding users with any email address or phone number.
• Substring filters suit cases where only a portion of the attribute value is known (e.g., users whose cn starts with "Ann" or whose mail contains "support"). They provide flexibility but should be used cautiously for performance reasons and only with supported attribute types.

Schema and directory implementation further influence efficiency:

• Many directories index equality and presence filter searches by default, but full or partial support for substring indexes is less common.
• Filters on unindexed or unsupported attributes may degrade search performance.
• Attempting a substring filter on a non-string attribute yields unpredictable or null results.

Common Pitfalls and Misconceptions

Several misunderstandings in LDAP filter construction can lead to subtle bugs or severe performance penalties:

• (attribute=*) is not a substring filter. It only tests for the presence of an attribute, not for any value containing the wildcard (RFC 4515).
• Leading wildcards are expensive. Filters like (cn=*doe) generally require scanning every value of the attribute, bypassing indexes. Prefer (cn=doe*) where possible.
• Not all attribute types support substring filters. Substring matching is only defined for human-readable, string attributes. Schema should always be consulted if in doubt.
• Equality may or may not be case-sensitive. Case sensitivity depends on the attribute's matching rule, which may perform normalization (such as lowercasing or whitespace collapse) automatically.

Practical Examples and Implementation Guidance

Let’s contrast these filters with real directory data:

Equality filter example:

• Filter: (uid=jsmith)
• Effect: Returns entries where the attribute uid is exactly "jsmith" according to its equality rule.

Presence filter example:

• Filter: (mail=*)
• Effect: Returns entries where the mail attribute exists (with any value), even if it is empty or not set for some entries.

Substring filter example:

• Filter: (cn=*Smith*)
• Effect: Returns entries where "Smith" appears anywhere in the cn value (e.g., "John Smith", "Smithsonian", "Eve Smithson").

Active Directory and product specifics:
Core RFC syntax applies across compliant directories, including Active Directory and OpenLDAP. Some products or clouds may add proprietary filters or nuance attribute casing and normalization—always verify against server documentation.

Summary Table: Syntax, Intent, and Performance

Note: Do not use (attribute=*) as a substring filter; it is always presence-only. For substring queries, ensure your attribute supports substring matching, and prefer right-truncated or contained wildcards for better performance.

By rigorously applying the correct LDAP filter type for your search scenario—and respecting schema, attribute type, and directory implementation—you can craft precise, robust, and performant directory queries. Use the RFC definitions as your reference point, and always validate filter logic and attribute support in your target environment.

Sources

• www.rfc-editor.org — rfc4515
• www.rfc-editor.org — rfc4511
• www.rfc-editor.org — rfc2254