Class: Net::LDAP::Filter

Inherits:
Object
  • Object
show all
Defined in:
lib/net/ldap/filter.rb

Overview

Class Net::LDAP::Filter is used to constrain LDAP searches. An object of this class is passed to Net::LDAP#search in the parameter :filter.

Net::LDAP::Filter supports the complete set of search filters available in LDAP, including conjunction, disjunction and negation (AND, OR, and NOT). This class supplants the (infamous) RFC-2254 standard notation for specifying LDAP search filters.

Here’s how to code the familiar “objectclass is present” filter:

f = Net::LDAP::Filter.pres( "objectclass" )

The object returned by this code can be passed directly to the :filter parameter of Net::LDAP#search.

See the individual class and instance methods below for more examples.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(op, a, b) ⇒ Filter

Returns a new instance of Filter.



51
52
53
54
55
 
# File 'lib/net/ldap/filter.rb', line 51

def initialize op, a, b
  @op = op
  @left = a
  @right = b
end

Class Method Details

.eq(attribute, value) ⇒ Object

#eq creates a filter object indicating that the value of a paticular attribute must be either present or must match a particular string.

To specify that an attribute is “present” means that only directory entries which contain a value for the particular attribute will be selected by the filter. This is useful in case of optional attributes such as mail. Presence is indicated by giving the value “*” in the second parameter to #eq. This example selects only entries that have one or more values for sAMAccountName:

f = Net::LDAP::Filter.eq( "sAMAccountName", "*" )

To match a particular range of values, pass a string as the second parameter to #eq. The string may contain one or more “*” characters as wildcards: these match zero or more occurrences of any character. Full regular-expressions are not supported due to limitations in the underlying LDAP protocol. This example selects any entry with a mail value containing the substring “anderson”:

f = Net::LDAP::Filter.eq( "mail", "*anderson*" )



79
 
# File 'lib/net/ldap/filter.rb', line 79

def Filter::eq attribute, value; Filter.new :eq, attribute, value; end

.ge(attribute, value) ⇒ Object 



83
 
# File 'lib/net/ldap/filter.rb', line 83

def Filter::ge attribute, value; Filter.new :ge, attribute, value; end

.gt(attribute, value) ⇒ Object 



81
 
# File 'lib/net/ldap/filter.rb', line 81

def Filter::gt attribute, value; Filter.new :gt, attribute, value; end

.le(attribute, value) ⇒ Object 



84
 
# File 'lib/net/ldap/filter.rb', line 84

def Filter::le attribute, value; Filter.new :le, attribute, value; end

.lt(attribute, value) ⇒ Object 



82
 
# File 'lib/net/ldap/filter.rb', line 82

def Filter::lt attribute, value; Filter.new :lt, attribute, value; end

.ne(attribute, value) ⇒ Object 



80
 
# File 'lib/net/ldap/filter.rb', line 80

def Filter::ne attribute, value; Filter.new :ne, attribute, value; end

.parse_ldap_filter(obj) ⇒ Object

– We get a Ruby object which comes from parsing an RFC-1777 “Filter” object. Convert it to a Net::LDAP::Filter. TODO, we’re hardcoding the RFC-1777 BER-encodings of the various filter types. Could pull them out into a constant.



244
245
246
247
248
249
250
251
252
253
 
# File 'lib/net/ldap/filter.rb', line 244

def Filter::parse_ldap_filter obj
  case obj.ber_identifier
  when 0x87         # present. context-specific primitive 7.
    Filter.eq( obj.to_s, "*" )
  when 0xa3         # equalityMatch. context-specific constructed 3.
    Filter.eq( obj[0], obj[1] )
  else
    raise LdapError.new( "unknown ldap search-filter type: #{obj.ber_identifier}" )
  end
end

.pres(attribute) ⇒ Object

#pres( attribute ) is a synonym for #eq( attribute, “*” )



88
 
# File 'lib/net/ldap/filter.rb', line 88

def Filter::pres attribute; Filter.eq attribute, "*"; end

Instance Method Details

#&(filter) ⇒ Object

operator & (“AND”) is used to conjoin two or more filters. This expression will select only entries that have an objectclass attribute AND have a mail attribute that begins with “George”:

f = Net::LDAP::Filter.pres( "objectclass" ) & Net::LDAP::Filter.eq( "mail", "George*" )



95
 
# File 'lib/net/ldap/filter.rb', line 95

def & filter; Filter.new :and, self, filter; end

#coalesce(operator) ⇒ Object

– coalesce This is a private helper method for dealing with chains of ANDs and ORs that are longer than two. If BOTH of our branches are of the specified type of joining operator, then return both of them as an array (calling coalesce recursively). If they’re not, then return an array consisting only of self.



228
229
230
231
232
233
234
 
# File 'lib/net/ldap/filter.rb', line 228

def coalesce operator
  if @op == operator
    [@left.coalesce( operator ), @right.coalesce( operator )]
  else
    [self]
  end
end

#match(entry) ⇒ Object

– We got a hash of attribute values. Do we match the attributes? Return T/F, and call match recursively as necessary.



260
261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/net/ldap/filter.rb', line 260

def match entry
  case @op
  when :eq
    if @right == "*"
      l = entry[@left] and l.length > 0
    else
      l = entry[@left] and l = l.to_a and l.index(@right)
    end
  else
    raise LdapError.new( "unknown filter type in match: #{@op}" )
  end
end

#to_ber ⇒ Object

– to_ber 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
    }
}

Parsing substrings is a little tricky. We use the split method to break a string into substrings delimited by the * (star) character. But we also need to know whether there is a star at the head and tail of the string. A Ruby particularity comes into play here: if you split on * and the first character of the string is a star, then split will return an array whose first element is an empty string. But if the last character of the string is star, then split will return an array that does not add an empty string at the end. So we have to deal with all that specifically.



179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/net/ldap/filter.rb', line 179

def to_ber
  case @op
  when :eq
    if @right == "*"          # present
      @left.to_ber_contextspecific 7
    elsif @right =~ /[\*]/    #substring
      ary = @right.split( /[\*]+/ )
      final_star = @right =~ /[\*]$/
      initial_star = ary.first == "" and ary.shift

      seq = []
      unless initial_star
        seq << ary.shift.to_ber_contextspecific(0)
      end
      n_any_strings = ary.length - (final_star ? 0 : 1)
      p n_any_strings
      n_any_strings.times {
        seq << ary.shift.to_ber_contextspecific(1)
      }
      unless final_star
        seq << ary.shift.to_ber_contextspecific(2)
      end
      [@left.to_ber, seq.to_ber].to_ber_contextspecific 4
    else                      #equality
      [@left.to_ber, @right.to_ber].to_ber_contextspecific 3
    end
  when :and
    ary = [@left.coalesce(:and), @right.coalesce(:and)].flatten
    ary.map {|a| a.to_ber}.to_ber_contextspecific( 0 )
  when :or
    ary = [@left.coalesce(:or), @right.coalesce(:or)].flatten
    ary.map {|a| a.to_ber}.to_ber_contextspecific( 1 )
  when :not
      [@left.to_ber].to_ber_contextspecific 2
  else
    # ERROR, we'll return objectclass=* to keep things from blowing up,
    # but that ain't a good answer and we need to kick out an error of some kind.
    raise "unimplemented search filter"
  end
end

#to_s ⇒ Object 



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/net/ldap/filter.rb', line 116

def to_s
  case @op
  when :ne
    "(!(#{@left}=#{@right}))"
  when :eq
    "(#{@left}=#{@right})"
  when :gt
    "#{@left}>#{@right}"
  when :lt
    "#{@left}<#{@right}"
  when :ge
    "#{@left}>=#{@right}"
  when :le
    "#{@left}<=#{@right}"
  when :and
    "(&(#{@left})(#{@right}))"
  when :or
    "(|(#{@left})(#{@right}))"
  when :not
    "(!(#{@left}))"
  else
    raise "invalid or unsupported operator in LDAP Filter"
  end
end

#|(filter) ⇒ Object

operator | (“OR”) is used to disjoin two or more filters. This expression will select entries that have either an objectclass attribute OR a mail attribute that begins with “George”:

f = Net::LDAP::Filter.pres( "objectclass" ) | Net::LDAP::Filter.eq( "mail", "George*" )



102
 
# File 'lib/net/ldap/filter.rb', line 102

def | filter; Filter.new :or, self, filter; end

#~@ ⇒ Object

operator ~ (“NOT”) is used to negate a filter. This expression will select only entries that do not have an objectclass attribute:

f = ~ Net::LDAP::Filter.pres( "objectclass" )

– This operator can’t be !, evidently. Try it.



113
 
# File 'lib/net/ldap/filter.rb', line 113

def ~@; Filter.new :not, self, nil; end