ruby-net-ldap 0.0.1 → 0.0.2

data/ChangeLog

@@ -1,5 +1,19 @@
 = Net::LDAP Changelog
 
+== Net::LDAP 0.0.2: July 12, 2006
+* Fixed malformation in distro tarball and gem.
+* Improved documentation.
+* Supported "paged search control."
+* Added a range of API improvements.
+* Thanks to Andre Nathan, andre@digirati.com.br, for valuable
+  suggestions.
+* Added support for LE and GE search filters.
+* Added support for Search referrals.
+* Fixed a regression with openldap 2.2.x and higher caused
+  by the introduction of RFC-2696 controls. Thanks to Andre
+  Nathan for reporting the problem.
+* Added support for RFC-2254 filter syntax.
+
 == Net::LDAP 0.0.1: May 1, 2006
 * Initial release.
 * Client functionality is near-complete, although the APIs

data/README

@@ -3,19 +3,22 @@ Net::LDAP is an LDAP support library written in pure Ruby. It supports all
 LDAP client features, and a subset of server features as well.
 
 Homepage::  http://rubyforge.org/projects/net-ldap/
-Copyright:: 2006 by Francis Cianfrocca
+Copyright:: (C) 2006 by Francis Cianfrocca
 
 Original developer: Francis Cianfrocca
 Contributions by Austin Ziegler gratefully acknowledged.
 
 == LICENCE NOTES
 Please read the file LICENCE for licensing restrictions on this library. In
-it simplest terms, this library is available under the same terms as Ruby
+the simplest terms, this library is available under the same terms as Ruby
 itself.
 
 == Requirements
 Net::LDAP requires Ruby 1.8.2 or better.
 
+== Documentation
+See Net::LDAP for documentation and usage samples.
+
 #--
 # Net::LDAP for Ruby.
 #   http://rubyforge.org/projects/net-ldap/
@@ -24,6 +27,6 @@ Net::LDAP requires Ruby 1.8.2 or better.
 #   Available under the same terms as Ruby. See LICENCE in the main
 #   distribution for full licensing information.
 #
-# $Id: README 82 2006-04-30 11:36:18Z blackhedd $
+# $Id: README 141 2006-07-12 10:37:37Z blackhedd $
 #++
 # vim: sts=2 sw=2 ts=4 et ai tw=77

data/lib/net/ldap.rb

@@ -1,4 +1,4 @@
-# $Id: ldap.rb 94 2006-05-01 07:19:12Z blackhedd $
+# $Id: ldap.rb 141 2006-07-12 10:37:37Z blackhedd $
 #
 # Net::LDAP for Ruby
 #
@@ -32,7 +32,7 @@ module Net
   # == Net::LDAP
   #
   # This library provides a pure-Ruby implementation of the
-  # LDAP client protocol, per RFC-1777.
+  # LDAP client protocol, per RFC-2251.
   # It can be used to access any server which implements the
   # LDAP protocol.
   #
@@ -41,7 +41,25 @@ module Net
   # the LDAP protocol itself, and thus presenting as Ruby-like
   # a programming interface as possible.
   # 
-  # === Quick-start for the Impatient
+  # == Quick-start for the Impatient
+  # === Quick Example of a user-authentication against an LDAP directory:
+  #
+  #  require 'rubygems'
+  #  require 'net/ldap'
+  #  
+  #  ldap = Net::LDAP.new
+  #  ldap.host = your_server_ip_address
+  #  ldap.port = 389
+  #  ldap.auth "joe_user", "opensesame"
+  #  if ldap.bind
+  #    # authentication succeeded
+  #  else
+  #    # authentication failed
+  #  end
+  #
+  #
+  # === Quick Example of a search against an LDAP directory:
+  #
   #  require 'rubygems'
   #  require 'net/ldap'
   #  
@@ -69,14 +87,14 @@ module Net
   #  p ldap.get_operation_result
   #  
   #
-  # == Quick introduction to LDAP
+  # == A Brief Introduction to LDAP
   #
-  # We're going to provide a quick and highly informal introduction to LDAP
+  # We're going to provide a quick, informal introduction to LDAP
   # terminology and
   # typical operations. If you're comfortable with this material, skip
   # ahead to "How to use Net::LDAP." If you want a more rigorous treatment
   # of this material, we recommend you start with the various IETF and ITU
-  # standards that control LDAP.
+  # standards that relate to LDAP.
   #
   # === Entities
   # LDAP is an Internet-standard protocol used to access directory servers.
@@ -116,17 +134,17 @@ module Net
   # range of attributes, and constrain their values according to standard
   # rules.
   #
-  # A good example of an attribute is <tt>cn,</tt> which stands for "Common Name."
-  # In many directories, this attribute is used to store a string consisting of
-  # a person's first and last names. Most directories enforce the convention that
-  # an entity's <tt>cn</tt> attribute have <i>exactly one</i> value. In LDAP
-  # jargon, that means that <tt>cn</tt> must be <i>present</i> and
+  # A good example of an attribute is <tt>sn,</tt> which stands for "Surname."
+  # This attribute is generally used to store a person's surname, or last name.
+  # Most directories enforce the standard convention that
+  # an entity's <tt>sn</tt> attribute have <i>exactly one</i> value. In LDAP
+  # jargon, that means that <tt>sn</tt> must be <i>present</i> and
   # <i>single-valued.</i>
   #
   # Another attribute is <tt>mail,</tt> which is used to store email addresses.
   # (No, there is no attribute called "email," perhaps because X.400 terminology
   # predates the invention of the term <i>email.</i>) <tt>mail</tt> differs
-  # from <tt>cn</tt> in that most directories permit any number of values for the
+  # from <tt>sn</tt> in that most directories permit any number of values for the
   # <tt>mail</tt> attribute, including zero.
   #
   #
@@ -173,7 +191,7 @@ module Net
   # set of attribute values for each entity, depending on what attributes the search requested.
   # 
   # ==== Add
-  # #add operation specifies a new DN and an initial set of attribute values. If the operation
+  # #add specifies a new DN and an initial set of attribute values. If the operation
   # succeeds, a new entity with the corresponding DN and attributes is added to the directory.
   #
   # ==== Modify
@@ -181,11 +199,11 @@ module Net
   # the attribute values stored in the directory for a particular entity.
   # #modify may add or delete attributes (which are lists of values) or it change attributes by
   # adding to or deleting from their values.
-  # There are three easier methods to modify an entry's attribute values:
+  # Net::LDAP provides three easier methods to modify an entry's attribute values:
   # #add_attribute, #replace_attribute, and #delete_attribute.
   #
   # ==== Delete
-  # #delete operation specifies an entity DN. If it succeeds, the entity and all its attributes
+  # #delete specifies an entity DN. If it succeeds, the entity and all its attributes
   # is removed from the directory.
   #
   # ==== Rename (or Modify RDN)
@@ -238,7 +256,7 @@ module Net
 
     class LdapError < Exception; end
 
-    VERSION = "0.0.1"
+    VERSION = "0.0.2"
 
 
     SearchScope_BaseObject = 0
@@ -266,6 +284,7 @@ module Net
           14 => :array,             # CompareRequest
           15 => :array,             # CompareResponse
           16 => :array,             # AbandonRequest
+          19 => :array,             # SearchResultReferral
           24 => :array,             # Unsolicited Notification
         }
       },
@@ -274,6 +293,10 @@ module Net
           0 => :string,             # password
           1 => :string,             # Kerberos v4
           2 => :string,             # Kerberos v5
+        },
+        :constructed => {
+          0 => :array,              # RFC-2251 Control
+          3 => :array,              # Seach referral
         }
       }
     }
@@ -281,12 +304,16 @@ module Net
     DefaultHost = "127.0.0.1"
     DefaultPort = 389
     DefaultAuth = {:method => :anonymous}
+    DefaultTreebase = "dc=com"
 
 
     ResultStrings = {
       0 => "Success",
       1 => "Operations Error",
       2 => "Protocol Error",
+      3 => "Time Limit Exceeded",
+      4 => "Size Limit Exceeded",
+      12 => "Unavailable crtical extension",
       16 => "No Such Attribute",
       17 => "Undefined Attribute Type",
       20 => "Attribute or Value Exists",
@@ -303,13 +330,23 @@ module Net
       68 => "Entry Already Exists"
     }
 
+
+    module LdapControls
+      PagedResults = "1.2.840.113556.1.4.319" # Microsoft evil from RFC 2696
+    end
+
+
     #
     # LDAP::result2string
     #
-    def LDAP::result2string code
+    def LDAP::result2string code # :nodoc:
       ResultStrings[code] || "unknown result (#{code})"
     end 
 
+
+    attr_accessor :host, :port, :base
+
+
     # Instantiate an object of type Net::LDAP to perform directory operations.
     # This constructor takes a Hash containing arguments. The following arguments
     # are supported:
@@ -318,6 +355,7 @@ module Net
     # * :auth => a Hash containing authorization parameters. Currently supported values include:
     #   {:method => :anonymous} and
     #   {:method => :simple, :username => your_user_name, :password => your_password }
+    #   The password parameter may be a Proc that returns a String.
     #
     # Instantiating a Net::LDAP object does <i>not</i> result in network traffic to
     # the LDAP server. It simply stores the connection and binding parameters in the
@@ -328,6 +366,11 @@ module Net
       @port = args[:port] || DefaultPort
       @verbose = false # Make this configurable with a switch on the class.
       @auth = args[:auth] || DefaultAuth
+      @base = args[:base] || DefaultTreebase
+
+      if pr = @auth[:password] and pr.respond_to?(:call)
+        @auth[:password] = pr.call
+      end
 
       # This variable is only set when we are created with LDAP::open.
       # All of our internal methods will connect using it, or else
@@ -335,6 +378,45 @@ module Net
       @open_connection = nil
     end
 
+    # Convenience method to specify authentication credentials to the LDAP
+    # server. Currently supports simple authentication requiring
+    # a username and password.
+    #
+    # Observe that on most LDAP servers,
+    # the username is a complete DN. However, with A/D, it's often possible
+    # to give only a user-name rather than a complete DN. In the latter
+    # case, beware that many A/D servers are configured to permit anonymous
+    # (uncredentialled) binding, and will silently accept your binding
+    # as anonymous if you give an unrecognized username. This is not usually
+    # what you want. (See #get_operation_result.)
+    #
+    # <b>Important:</b> The password argument may be a Proc that returns a string.
+    # This makes it possible for you to write client programs that solicit
+    # passwords from users or from other data sources without showing them
+    # in your code or on command lines.
+    #
+    #  require 'net/ldap'
+    #  
+    #  ldap = Net::LDAP.new
+    #  ldap.host = server_ip_address
+    #  ldap.authenticate "cn=Your Username,cn=Users,dc=example,dc=com", "your_psw"
+    #
+    # Alternatively (with a password block):
+    #
+    #  require 'net/ldap'
+    #  
+    #  ldap = Net::LDAP.new
+    #  ldap.host = server_ip_address
+    #  psw = proc { your_psw_function }
+    #  ldap.authenticate "cn=Your Username,cn=Users,dc=example,dc=com", psw
+    #
+    def authenticate username, password
+      password = password.call if password.respond_to?(:call)
+      @auth = {:method => :simple, :username => username, :password => password}
+    end
+
+    alias_method :auth, :authenticate
+
     # #open takes the same parameters as #new. #open makes a network connection to the
     # LDAP server and then passes a newly-created Net::LDAP object to the caller-supplied block.
     # Within the block, you can call any of the instance methods of Net::LDAP to
@@ -409,38 +491,6 @@ module Net
     end
 
 
-    # <i>DEPRECATED.</i> Performs an LDAP search, waits for the operation to complete, and
-    # passes a result set to the caller-supplied block.
-    #--
-    # If an open call is in progress (@open_connection will be non-nil),
-    # then ASSUME a bind has been performed and accepted, and just
-    # execute the search.
-    # If @open_connection is nil, then we have to connect, bind,
-    # search, and then disconnect. (The disconnect is not strictly
-    # necessary but it's friendlier to the network to do it here
-    # rather than waiting for Ruby's GC.)
-    # Note that in the standalone case, we're permitting the caller
-    # to modify the auth parms.
-    #
-    def searchx args
-      if @open_connection
-        @result = @open_connection.searchx( args ) {|values|
-          yield( values ) if block_given?
-        }
-      else
-        @result = 0
-        conn = Connection.new( :host => @host, :port => @port )
-        if (@result = conn.bind( args[:auth] || @auth )) == 0
-          @result = conn.searchx( args ) {|values|
-            yield( values ) if block_given?
-          }
-        end
-        conn.close
-      end
-
-      @result == 0
-    end
-
     # Searches the LDAP directory for directory entries.
     # Takes a hash argument with parameters. Supported parameters include:
     # * :base (a string specifying the tree-base for the search);
@@ -456,6 +506,8 @@ module Net
     # be called 1000 times. If the search returns no entries, the block will
     # not be called.
     #
+    #--
+    # ORIGINAL TEXT, replaced 04May06.
     # #search returns either a result-set or a boolean, depending on the
     # value of the <tt>:return_result</tt> argument. The default behavior is to return
     # a result set, which is a hash. Each key in the hash is a string specifying
@@ -463,6 +515,13 @@ module Net
     # If you request a result set and #search fails with an error, it will return nil.
     # Call #get_operation_result to get the error information returned by
     # the LDAP server.
+    #++
+    # #search returns either a result-set or a boolean, depending on the
+    # value of the <tt>:return_result</tt> argument. The default behavior is to return
+    # a result set, which is an Array of objects of class Net::LDAP::Entry.
+    # If you request a result set and #search fails with an error, it will return nil.
+    # Call #get_operation_result to get the error information returned by
+    # the LDAP server.
     #
     # When <tt>:return_result => false,</tt> #search will
     # return only a Boolean, to indicate whether the operation succeeded. This can improve performance
@@ -503,12 +562,19 @@ module Net
     # that the caller can set to suppress the return of a result set,
     # if he's planning to process every entry as it comes from the server.
     #
-    def search args
-      result_set = (args and args[:return_result] == false) ? nil : {}
+    # REINTERPRETED the result set, 04May06. Originally this was a hash
+    # of entries keyed by DNs. But let's get away from making users
+    # handle DNs. Change it to a plain array. Eventually we may
+    # want to return a Dataset object that delegates to an internal
+    # array, so we can provide sort methods and what-not.
+    #
+    def search args = {}
+      args[:base] ||= @base
+      result_set = (args and args[:return_result] == false) ? nil : []
 
       if @open_connection
         @result = @open_connection.search( args ) {|entry|
-          result_set[entry.dn] = entry if result_set
+          result_set << entry if result_set
           yield( entry ) if block_given?
         }
       else
@@ -516,7 +582,7 @@ module Net
         conn = Connection.new( :host => @host, :port => @port )
         if (@result = conn.bind( args[:auth] || @auth )) == 0
           @result = conn.search( args ) {|entry|
-            (result_set[entry.dn] = entry) if result_set
+            result_set << entry if result_set
             yield( entry ) if block_given?
           }
         end
@@ -526,12 +592,46 @@ module Net
       @result == 0 and result_set
     end
 
-    # #bind connects to the LDAP server and requests authentication
+    # #bind connects to an LDAP server and requests authentication
     # based on the <tt>:auth</tt> parameter passed to #open or #new.
     # It takes no parameters.
-    # User code generally will not call #bind. It will be called
-    # implicitly by the library whenever an LDAP operation is
-    # requested. #bind can be useful to test authentication.
+    #
+    # User code does not need to call #bind directly. It will be called
+    # implicitly by the library whenever you invoke an LDAP operation,
+    # such as #search or #add.
+    #
+    # It is useful, however, to call #bind in your own code when the
+    # only operation you intend to perform against the directory is
+    # to validate a login credential. #bind returns true or false
+    # to indicate whether the binding was successful. Reasons for
+    # failure include malformed or unrecognized usernames and
+    # incorrect passwords. Use #get_operation_result to find out
+    # what happened in case of failure.
+    #
+    # Here's a typical example using #bind to authenticate a
+    # credential which was (perhaps) solicited from the user of a
+    # web site:
+    #
+    #  require 'net/ldap'
+    #  ldap = Net::LDAP.new
+    #  ldap.host = your_server_ip_address
+    #  ldap.port = 389
+    #  ldap.auth your_user_name, your_user_password
+    #  if ldap.bind
+    #    # authentication succeeded
+    #  else
+    #    # authentication failed
+    #    p ldap.get_operation_result
+    #  end
+    #
+    # You don't have to create a new instance of Net::LDAP every time
+    # you perform a binding in this way. If you prefer, you can cache the Net::LDAP object
+    # and re-use it to perform subsequent bindings, <i>provided</i> you call
+    # #auth to specify a new credential before calling #bind. Otherwise, you'll
+    # just re-authenticate the previous user! (You don't need to re-set
+    # the values of #host and #port.) As noted in the documentation for #auth,
+    # the password parameter can be a Ruby Proc instead of a String.
+    #
     #--
     # If there is an @open_connection, then perform the bind
     # on it. Otherwise, connect, bind, and disconnect.
@@ -864,92 +964,109 @@ module Net
     #--
     # WARNING: this code substantially recapitulates the searchx method.
     #
+    # 02May06: Well, I added support for RFC-2696-style paged searches.
+    # This is used on all queries because the extension is marked non-critical.
+    # As far as I know, only A/D uses this, but it's required for A/D. Otherwise
+    # you won't get more than 1000 results back from a query.
+    # This implementation is kindof clunky and should probably be refactored.
+    # Also, is it my imagination, or are A/Ds the slowest directory servers ever???
+    #
     def search args = {}
       search_filter = (args && args[:filter]) || Filter.eq( "objectclass", "*" )
       search_base = (args && args[:base]) || "dc=example,dc=com"
       search_attributes = ((args && args[:attributes]) || []).map {|attr| attr.to_s.to_ber}
+      return_referrals = args && args[:return_referrals] == true
 
       attributes_only = (args and args[:attributes_only] == true)
       scope = args[:scope] || Net::LDAP::SearchScope_WholeSubtree
       raise LdapError.new( "invalid search scope" ) unless SearchScopes.include?(scope)
 
-      request = [
-        search_base.to_ber,
-        scope.to_ber_enumerated,
-        0.to_ber_enumerated,
-        0.to_ber,
-        0.to_ber,
-        attributes_only.to_ber,
-        search_filter.to_ber,
-        search_attributes.to_ber_sequence
-      ].to_ber_appsequence(3)
-      pkt = [next_msgid.to_ber, request].to_ber_sequence
-      @conn.write pkt
-
+      # An interesting value for the size limit would be close to A/D's built-in
+      # page limit of 1000 records, but openLDAP newer than version 2.2.0 chokes
+      # on anything bigger than 126. You get a silent error that is easily visible
+      # by running slapd in debug mode. Go figure.
+      rfc2696_cookie = [126, ""]
       result_code = 0
 
-      while (be = @conn.read_ber(AsnSyntax)) && (pdu = LdapPdu.new( be ))
-        case pdu.app_tag
-        when 4 # search-data
-          yield( pdu.search_entry ) if block_given?
-        when 5 # search-result
-          result_code = pdu.result_code
-          break
-        else
-          raise LdapError.new( "invalid response-type in search: #{pdu.app_tag}" )
+      loop {
+        # should collect this into a private helper to clarify the structure
+
+        request = [
+          search_base.to_ber,
+          scope.to_ber_enumerated,
+          0.to_ber_enumerated,
+          0.to_ber,
+          0.to_ber,
+          attributes_only.to_ber,
+          search_filter.to_ber,
+          search_attributes.to_ber_sequence
+        ].to_ber_appsequence(3)
+  
+        controls = [
+          [
+          LdapControls::PagedResults.to_ber,
+          false.to_ber, # criticality MUST be false to interoperate with normal LDAPs.
+          rfc2696_cookie.map{|v| v.to_ber}.to_ber_sequence.to_s.to_ber
+          ].to_ber_sequence
+        ].to_ber_contextspecific(0)
+
+        pkt = [next_msgid.to_ber, request, controls].to_ber_sequence
+        @conn.write pkt
+
+        result_code = 0
+        controls = []
+
+        while (be = @conn.read_ber(AsnSyntax)) && (pdu = LdapPdu.new( be ))
+          case pdu.app_tag
+          when 4 # search-data
+            yield( pdu.search_entry ) if block_given?
+          when 19 # search-referral
+            if return_referrals
+              if block_given?
+                se = Net::LDAP::Entry.new
+                se[:search_referrals] = (pdu.search_referrals || [])
+                yield se
+              end
+            end
+            #p pdu.referrals
+          when 5 # search-result
+            result_code = pdu.result_code
+            controls = pdu.result_controls
+            break
+          else
+            raise LdapError.new( "invalid response-type in search: #{pdu.app_tag}" )
+          end
         end
-      end
 
-      result_code
-    end
+        # When we get here, we have seen a type-5 response.
+        # If there is no error AND there is an RFC-2696 cookie,
+        # then query again for the next page of results.
+        # If not, we're done.
+        # Don't screw this up or we'll break every search we do.
+        more_pages = false
+        if result_code == 0 and controls
+          controls.each do |c|
+            if c.oid == LdapControls::PagedResults
+              more_pages = false # just in case some bogus server sends us >1 of these.
+              if c.value and c.value.length > 0
+                cookie = c.value.read_ber[1]
+                if cookie and cookie.length > 0
+                  rfc2696_cookie[1] = cookie
+                  more_pages = true
+                end
+              end
+            end
+          end
+        end
 
+        break unless more_pages
+      } # loop
 
-    #--
-    # searchx
-    # Original implementation, this doesn't return until all data have been
-    # received from the server.
-    # TODO, certain search parameters are hardcoded.
-    # TODO, if we mis-parse the server results or the results are wrong, we can block
-    # forever. That's because we keep reading results until we get a type-5 packet,
-    # which might never come. We need to support the time-limit in the protocol.
-    #--
-    # WARNING: this code substantially recapitulates the search method.
-    #
-    def searchx args
-      search_filter = (args && args[:filter]) || Filter.eq( "objectclass", "*" )
-      search_base = (args && args[:base]) || "dc=example,dc=com"
-      search_attributes = ((args && args[:attributes]) || []).map {|attr| attr.to_s.to_ber}
-      request = [
-        search_base.to_ber,
-        2.to_ber_enumerated,
-        0.to_ber_enumerated,
-        0.to_ber,
-        0.to_ber,
-        false.to_ber,
-        search_filter.to_ber,
-        search_attributes.to_ber_sequence
-      ].to_ber_appsequence(3)
-      pkt = [next_msgid.to_ber, request].to_ber_sequence
-      @conn.write pkt
+      result_code
+    end
 
-      search_results = {}
-      result_code = 0
 
-      while (be = @conn.read_ber(AsnSyntax)) && (pdu = LdapPdu.new( be ))
-        case pdu.app_tag
-        when 4 # search-data
-          search_results [pdu.search_dn] = pdu.search_attributes
-        when 5 # search-result
-          result_code = pdu.result_code
-          block_given? and yield( search_results )
-          break
-        else
-          raise LdapError.new( "invalid response-type in search: #{pdu.app_tag}" )
-        end
-      end
 
-      result_code
-    end
 
     #--
     # modify

data/lib/net/ldap/entry.rb

@@ -1,4 +1,4 @@
-# $Id: entry.rb 95 2006-05-01 12:19:16Z blackhedd $
+# $Id: entry.rb 123 2006-05-18 03:52:38Z blackhedd $
 #
 # LDAP Entry (search-result) support classes
 #
@@ -33,46 +33,129 @@ module Net
 class LDAP
 
 
+  # Objects of this class represent individual entries in an LDAP
+  # directory. User code generally does not instantiate this class.
+  # Net::LDAP#search provides objects of this class to user code,
+  # either as block parameters or as return values.
+  #
+  # In LDAP-land, an "entry" is a collection of attributes that are
+  # uniquely and globally identified by a DN ("Distinguished Name").
+  # Attributes are identified by short, descriptive words or phrases.
+  # Although a directory is
+  # free to implement any attribute name, most of them follow rigorous
+  # standards so that the range of commonly-encountered attribute
+  # names is not large.
+  #
+  # An attribute name is case-insensitive. Most directories also
+  # restrict the range of characters allowed in attribute names.
+  # To simplify handling attribute names, Net::LDAP::Entry
+  # internally converts them to a standard format. Therefore, the
+  # methods which take attribute names can take Strings or Symbols,
+  # and work correctly regardless of case or capitalization.
+  #
+  # An attribute consists of zero or more data items called
+  # <i>values.</i> An entry is the combination of a unique DN, a set of attribute
+  # names, and a (possibly-empty) array of values for each attribute.
+  #
+  # Class Net::LDAP::Entry provides convenience methods for dealing
+  # with LDAP entries.
+  # In addition to the methods documented below, you may access individual
+  # attributes of an entry simply by giving the attribute name as
+  # the name of a method call. For example:
+  #  ldap.search( ... ) do |entry|
+  #    puts "Common name: #{entry.cn}"
+  #    puts "Email addresses:"
+  #      entry.mail.each {|ma| puts ma}
+  #  end
+  # If you use this technique to access an attribute that is not present
+  # in a particular Entry object, a NoMethodError exception will be raised.
+  #
+  #--
+  # Ugly problem to fix someday: We key off the internal hash with
+  # a canonical form of the attribute name: convert to a string,
+  # downcase, then take the symbol. Unfortunately we do this in
+  # at least three places. Should do it in ONE place.
   class Entry
 
-    def initialize dn = nil
+    # This constructor is not generally called by user code.
+    def initialize dn = nil # :nodoc:
       @myhash = Hash.new {|k,v| k[v] = [] }
       @myhash[:dn] = [dn]
     end
 
 
-    def []= name, value
+    def []= name, value # :nodoc:
       sym = name.to_s.downcase.intern
       @myhash[sym] = value
     end
 
 
     #--
-    # We have to deal with this one as we do []=
+    # We have to deal with this one as we do with []=
     # because this one and not the other one gets called
     # in formulations like entry["CN"] << cn.
     #
-    def [] name
+    def [] name # :nodoc:
       name = name.to_s.downcase.intern unless name.is_a?(Symbol)
       @myhash[name]
     end
 
+    # Returns the dn of the Entry as a String.
     def dn
       self[:dn][0]
     end
 
+    # Returns an array of the attribute names present in the Entry.
     def attribute_names
       @myhash.keys
     end
 
+    # Accesses each of the attributes present in the Entry.
+    # Calls a user-supplied block with each attribute in turn,
+    # passing two arguments to the block: a Symbol giving
+    # the name of the attribute, and a (possibly empty)
+    # Array of data values.
+    #
     def each
       if block_given?
-        attribute_names.each {|a| yield a, self[a] }
+        attribute_names.each {|a|
+          attr_name,values = a,self[a]
+          yield attr_name, values
+        }
       end
     end
 
     alias_method :each_attribute, :each
 
+
+    #--
+    # Convenience method to convert unknown method names
+    # to attribute references. Of course the method name
+    # comes to us as a symbol, so let's save a little time
+    # and not bother with the to_s.downcase two-step.
+    # Of course that means that a method name like mAIL
+    # won't work, but we shouldn't be encouraging that
+    # kind of bad behavior in the first place.
+    # Maybe we should thow something if the caller sends
+    # arguments or a block...
+    #
+    def method_missing *args, &block # :nodoc:
+      s = args[0].to_s.downcase.intern
+      if attribute_names.include?(s)
+        self[s]
+      elsif s.to_s[-1] == 61 and s.to_s.length > 1
+        value = args[1] or raise RuntimeError.new( "unable to set value" )
+        value = [value] unless value.is_a?(Array)
+        name = s.to_s[0..-2].intern
+        self[name] = value
+      else
+        raise NoMethodError.new( "undefined method '#{s}'" )
+      end
+    end
+
+    def write
+    end
+
   end # class Entry
 
 

data/lib/net/ldap/filter.rb

@@ -1,4 +1,4 @@
-# $Id: filter.rb 78 2006-04-26 02:57:34Z blackhedd $
+# $Id: filter.rb 132 2006-06-27 17:35:18Z blackhedd $
 #
 #
 #----------------------------------------------------------------------------
@@ -75,11 +75,13 @@ class Filter
   # This example selects any entry with a <tt>mail</tt> value containing
   # the substring "anderson":
   #  f = Net::LDAP::Filter.eq( "mail", "*anderson*" )
+  #--
+  # Removed gt and lt. They ain't in the standard!
   #
   def Filter::eq attribute, value; Filter.new :eq, attribute, value; end
   def Filter::ne attribute, value; Filter.new :ne, attribute, value; end
-  def Filter::gt attribute, value; Filter.new :gt, attribute, value; end
-  def Filter::lt attribute, value; Filter.new :lt, attribute, value; end
+  #def Filter::gt attribute, value; Filter.new :gt, attribute, value; end
+  #def Filter::lt attribute, value; Filter.new :lt, attribute, value; end
   def Filter::ge attribute, value; Filter.new :ge, attribute, value; end
   def Filter::le attribute, value; Filter.new :le, attribute, value; end
 
@@ -110,6 +112,7 @@ class Filter
   #
   #--
   # This operator can't be !, evidently. Try it.
+  # Removed GT and LT. They're not in the RFC.
   def ~@; Filter.new :not, self, nil; end
 
 
@@ -119,10 +122,10 @@ class Filter
       "(!(#{@left}=#{@right}))"
     when :eq
       "(#{@left}=#{@right})"
-    when :gt
-      "#{@left}>#{@right}"
-    when :lt
-      "#{@left}<#{@right}"
+    #when :gt
+     # "#{@left}>#{@right}"
+    #when :lt
+     # "#{@left}<#{@right}"
     when :ge
       "#{@left}>=#{@right}"
     when :le
@@ -180,7 +183,7 @@ class Filter
     case @op
     when :eq
       if @right == "*"          # present
-        @left.to_ber_contextspecific 7
+        @left.to_s.to_ber_contextspecific 7
       elsif @right =~ /[\*]/    #substring
         ary = @right.split( /[\*]+/ )
         final_star = @right =~ /[\*]$/
@@ -191,17 +194,21 @@ class Filter
           seq << ary.shift.to_ber_contextspecific(0)
         end
         n_any_strings = ary.length - (final_star ? 0 : 1)
-        p n_any_strings
+        #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
+        [@left.to_s.to_ber, seq.to_ber].to_ber_contextspecific 4
       else                      #equality
-        [@left.to_ber, @right.to_ber].to_ber_contextspecific 3
+        [@left.to_s.to_ber, @right.to_ber].to_ber_contextspecific 3
       end
+    when :ge
+      [@left.to_s.to_ber, @right.to_ber].to_ber_contextspecific 5
+    when :le
+      [@left.to_s.to_ber, @right.to_ber].to_ber_contextspecific 6
     when :and
       ary = [@left.coalesce(:and), @right.coalesce(:and)].flatten
       ary.map {|a| a.to_ber}.to_ber_contextspecific( 0 )
@@ -270,9 +277,106 @@ class Filter
     end
   end
 
+  # Converts an LDAP filter-string (in the prefix syntax specified in RFC-2254)
+  # to a Net::LDAP::Filter.
+  def self.construct ldap_filter_string
+    FilterParser.new(ldap_filter_string).filter
+  end
+
+  # Synonym for #construct.
+  # to a Net::LDAP::Filter.
+  def self.from_rfc2254 ldap_filter_string
+    construct ldap_filter_string
+  end
 
 end # class Net::LDAP::Filter
 
+
+class FilterParser #:nodoc:
+
+  attr_reader :filter
+
+  def initialize str
+    require 'strscan'
+    @filter = parse( StringScanner.new( str )) or raise Net::LDAP::LdapError.new( "invalid filter syntax" )
+  end
+
+  def parse scanner
+    parse_filter_branch(scanner) or parse_paren_expression(scanner)
+  end
+
+  def parse_paren_expression scanner
+    if scanner.scan /\s*\(\s*/
+      b = if scanner.scan /\s*\&\s*/
+        a = nil
+        branches = []
+        while br = parse_paren_expression(scanner)
+          branches << br
+        end
+        if branches.length >= 2
+          a = branches.shift
+          while branches.length > 0
+            a = a & branches.shift
+          end
+          a
+        end
+      elsif scanner.scan /\s*\|\s*/
+        # TODO: DRY!
+        a = nil
+        branches = []
+        while br = parse_paren_expression(scanner)
+          branches << br
+        end
+        if branches.length >= 2
+          a = branches.shift
+          while branches.length > 0
+            a = a | branches.shift
+          end
+          a
+        end
+      elsif scanner.scan /\s*\!\s*/
+        br = parse_paren_expression(scanner)
+        if br
+          ~ br
+        end
+      else
+        parse_filter_branch( scanner )
+      end
+
+      if b and scanner.scan( /\s*\)\s*/ )
+        b
+      end
+    end
+  end
+
+  def parse_filter_branch scanner
+    scanner.scan /\s*/
+    if token = scanner.scan( /[\w\-_]+/ )
+      scanner.scan /\s*/
+      if op = scanner.scan( /\=|\<\=|\<|\>\=|\>|\!\=/ )
+        scanner.scan /\s*/
+        if value = scanner.scan( /[\w\*\.]+/ )
+          case op
+          when "="
+            Filter.eq( token, value )
+          when "!="
+            Filter.ne( token, value )
+          when "<"
+            Filter.lt( token, value )
+          when "<="
+            Filter.le( token, value )
+          when ">"
+            Filter.gt( token, value )
+          when ">="
+            Filter.ge( token, value )
+          end
+        end
+      end
+    end
+  end
+
+end # class Net::LDAP::FilterParser
+
 end # class Net::LDAP
 end # module Net
 

data/lib/net/ldap/pdu.rb

@@ -1,4 +1,4 @@
-# $Id: pdu.rb 85 2006-04-30 16:31:08Z blackhedd $
+# $Id: pdu.rb 126 2006-05-31 15:55:16Z blackhedd $
 #
 # LDAP PDU support classes
 #
@@ -43,15 +43,20 @@ class LdapPdu
   AddResponse = 9
   DeleteResponse = 11
   ModifyRDNResponse = 13
+  SearchResultReferral = 19
 
   attr_reader :msg_id, :app_tag
   attr_reader :search_dn, :search_attributes, :search_entry
+  attr_reader :search_referrals
 
   #
   # initialize
   # An LDAP PDU always looks like a BerSequence with
-  # two elements: an integer (message-id number), and
+  # at least two elements: an integer (message-id number), and
   # an application-specific sequence.
+  # Some LDAPv3 packets also include an optional
+  # third element, which is a sequence of "controls"
+  # (See RFC 2251, section 4.1.12).
   # The application-specific tag in the sequence tells
   # us what kind of packet it is, and each kind has its
   # own format, defined in RFC-1777.
@@ -62,6 +67,10 @@ class LdapPdu
   # it remains to be seen whether there are servers out
   # there that will not work well with our approach.
   #
+  # Added a controls-processor to SearchResult.
+  # Didn't add it everywhere because it just _feels_
+  # like it will need to be refactored.
+  #
   def initialize ber_object
     begin
       @msg_id = ber_object[0].to_i
@@ -76,8 +85,11 @@ class LdapPdu
       parse_ldap_result ber_object[1]
     when SearchReturnedData
       parse_search_return ber_object[1]
+    when SearchResultReferral
+      parse_search_referral ber_object[1]
     when SearchResult
       parse_ldap_result ber_object[1]
+      parse_controls(ber_object[2]) if ber_object[2]
     when ModifyResponse
       parse_ldap_result ber_object[1]
     when AddResponse
@@ -101,8 +113,12 @@ class LdapPdu
     @ldap_result and @ldap_result[code]
   end
 
+  # Return RFC-2251 Controls if any.
+  # Messy. Does this functionality belong somewhere else?
+  def result_controls
+    @ldap_controls || []
+  end
 
-  private
 
   #
   # parse_ldap_result
@@ -111,6 +127,7 @@ class LdapPdu
     sequence.length >= 3 or raise LdapPduError
     @ldap_result = {:resultCode => sequence[0], :matchedDN => sequence[1], :errorMessage => sequence[2]}
   end
+  private :parse_ldap_result
 
   #
   # parse_search_return
@@ -136,17 +153,50 @@ class LdapPdu
   # we also return @search_entry, which is an LDAP::Entry object.
   # If that works out well, then we'll remove the first two.
   #
+  # Provisionally removed obsolete search_attributes and search_dn, 04May06.
+  #
   def parse_search_return sequence
     sequence.length >= 2 or raise LdapPduError
     @search_entry = LDAP::Entry.new( sequence[0] )
-    @search_dn = sequence[0]
-    @search_attributes = {}
+    #@search_dn = sequence[0]
+    #@search_attributes = {}
     sequence[1].each {|seq|
       @search_entry[seq[0]] = seq[1]
-      @search_attributes[seq[0].downcase.intern] = seq[1]
+      #@search_attributes[seq[0].downcase.intern] = seq[1]
     }
   end
 
+  #
+  # A search referral is a sequence of one or more LDAP URIs.
+  # Any number of search-referral replies can be returned by the server, interspersed
+  # with normal replies in any order.
+  # Until I can think of a better way to do this, we'll return the referrals as an array.
+  # It'll be up to higher-level handlers to expose something reasonable to the client.
+  def parse_search_referral uris
+    @search_referrals = uris
+  end
+
+
+  # Per RFC 2251, an LDAP "control" is a sequence of tuples, each consisting
+  # of an OID, a boolean criticality flag defaulting FALSE, and an OPTIONAL
+  # Octet String. If only two fields are given, the second one may be
+  # either criticality or data, since criticality has a default value.
+  # Someday we may want to come back here and add support for some of
+  # more-widely used controls. RFC-2696 is a good example.
+  #
+  def parse_controls sequence
+    @ldap_controls = sequence.map do |control|
+      o = OpenStruct.new
+      o.oid,o.criticality,o.value = control[0],control[1],control[2]
+      if o.criticality and o.criticality.is_a?(String)
+        o.value = o.criticality
+        o.criticality = false
+      end
+      o
+    end
+  end
+  private :parse_controls
+
 
 end
 

data/tests/testem.rb

@@ -1,4 +1,4 @@
-# $Id: testem.rb 72 2006-04-24 21:58:14Z blackhedd $
+# $Id: testem.rb 121 2006-05-15 18:36:24Z blackhedd $
 #
 #
 
@@ -7,5 +7,6 @@ require 'tests/testber'
 require 'tests/testldif'
 require 'tests/testldap'
 require 'tests/testpsw'
+require 'tests/testfilter'
 
 

data/tests/testfilter.rb

@@ -0,0 +1,37 @@
+# $Id: testfilter.rb 122 2006-05-15 20:03:56Z blackhedd $
+#
+#
+
+require 'test/unit'
+
+$:.unshift "lib"
+
+require 'net/ldap'
+
+
+class TestFilter < Test::Unit::TestCase
+
+  def setup
+  end
+
+
+  def teardown
+  end
+
+  def test_rfc_2254
+    p Net::LDAP::Filter.from_rfc2254( " ( uid=george*   ) " )
+    p Net::LDAP::Filter.from_rfc2254( "uid!=george*" )
+    p Net::LDAP::Filter.from_rfc2254( "uid<george*" )
+    p Net::LDAP::Filter.from_rfc2254( "uid <= george*" )
+    p Net::LDAP::Filter.from_rfc2254( "uid>george*" )
+    p Net::LDAP::Filter.from_rfc2254( "uid>=george*" )
+    p Net::LDAP::Filter.from_rfc2254( "uid!=george*" )
+
+    p Net::LDAP::Filter.from_rfc2254( "(& (uid!=george* ) (mail=*))" )
+    p Net::LDAP::Filter.from_rfc2254( "(| (uid!=george* ) (mail=*))" )
+    p Net::LDAP::Filter.from_rfc2254( "(! (mail=*))" )
+  end
+
+
+end
+

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: ruby-net-ldap
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
-date: 2006-05-01 00:00:00 -04:00
+  version: 0.0.2
+date: 2006-07-12 00:00:00 -04:00
 summary: A pure Ruby LDAP client library.
 require_paths: 
 - lib
@@ -32,6 +32,7 @@ files:
 - LICENCE
 - ChangeLog
 - COPYING
+- tests/testfilter.rb
 - tests/testpsw.rb
 - tests/testem.rb
 - tests/testdata.ldif