# $Id$ # # Net::LDAP for Ruby # # # Copyright (C) 2006 by Francis Cianfrocca. All Rights Reserved. # # Written and maintained by Francis Cianfrocca, gmail: garbagecat10. # # This program is free software. # You may re-distribute and/or modify this program under the same terms # as Ruby itself: Ruby Distribution License or GNU General Public License. # # # See Net::LDAP for documentation and usage samples. # require 'socket' require 'ostruct' require 'net/ber' require 'net/ldap/pdu' require 'net/ldap/filter' require 'net/ldap/dataset' require 'net/ldap/psw' require 'net/ldap/entry' module Net # == Net::LDAP # # This library provides a pure-Ruby implementation of the # LDAP client protocol, per RFC-1777. # It can be used to access any server which implements the # LDAP protocol. # # Net::LDAP is intended to provide full LDAP functionality # while hiding the more arcane aspects # the LDAP protocol itself, and thus presenting as Ruby-like # a programming interface as possible. # # === Quick-start for the Impatient # require 'rubygems' # require 'net/ldap' # # ldap = Net::LDAP.new :host => server_ip_address, # :port => 389, # :auth => { # :method => :simple, # :username => "cn=manager,dc=example,dc=com", # :password => "opensesame" # } # # filter = Net::LDAP::Filter.eq( "cn", "George*" ) # treebase = "dc=example,dc=com" # # ldap.search( :base => treebase, :filter => filter ) do |entry| # puts "DN: #{entry.dn}" # entry.each do |attribute, values| # puts " #{attribute}:" # values.each do |value| # puts " --->#{value}" # end # end # end # # p ldap.get_operation_result # # # == Quick introduction to LDAP # # We're going to provide a quick and highly 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. # # === Entities # LDAP is an Internet-standard protocol used to access directory servers. # The basic search unit is the entity, which corresponds to # a person or other domain-specific object. # A directory service which supports the LDAP protocol typically # stores information about a number of entities. # # === Principals # LDAP servers are typically used to access information about people, # but also very often about such items as printers, computers, and other # resources. To reflect this, LDAP uses the term entity, or less # commonly, principal, to denote its basic data-storage unit. # # # === Distinguished Names # In LDAP's view of the world, # an entity is uniquely identified by a globally-unique text string # called a Distinguished Name, originally defined in the X.400 # standards from which LDAP is ultimately derived. # Much like a DNS hostname, a DN is a "flattened" text representation # of a string of tree nodes. Also like DNS (and unlike Java package # names), a DN expresses a chain of tree-nodes written from left to right # in order from the most-resolved node to the most-general one. # # If you know the DN of a person or other entity, then you can query # an LDAP-enabled directory for information (attributes) about the entity. # Alternatively, you can query the directory for a list of DNs matching # a set of criteria that you supply. # # === Attributes # # In the LDAP view of the world, a DN uniquely identifies an entity. # Information about the entity is stored as a set of Attributes. # An attribute is a text string which is associated with zero or more # values. Most LDAP-enabled directories store a well-standardized # range of attributes, and constrain their values according to standard # rules. # # A good example of an attribute is sn, 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 sn attribute have exactly one value. In LDAP # jargon, that means that sn must be present and # single-valued. # # Another attribute is mail, 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 email.) mail differs # from sn in that most directories permit any number of values for the # mail attribute, including zero. # # # === Tree-Base # We said above that X.400 Distinguished Names are globally unique. # In a manner reminiscent of DNS, LDAP supposes that each directory server # contains authoritative attribute data for a set of DNs corresponding # to a specific sub-tree of the (notional) global directory tree. # This subtree is generally configured into a directory server when it is # created. It matters for this discussion because most servers will not # allow you to query them unless you specify a correct tree-base. # # Let's say you work for the engineering department of Big Company, Inc., # whose internet domain is bigcompany.com. You may find that your departmental # directory is stored in a server with a defined tree-base of # ou=engineering,dc=bigcompany,dc=com # You will need to supply this string as the tree-base when querying this # directory. (Ou is a very old X.400 term meaning "organizational unit." # Dc is a more recent term meaning "domain component.") # # === LDAP Versions # (stub, discuss v2 and v3) # # === LDAP Operations # The essential operations are: #bind, #search, #add, #modify, #delete, and #rename. # ==== Bind # #bind supplies a user's authentication credentials to a server, which in turn verifies # or rejects them. There is a range of possibilities for credentials, but most directories # support a simple username and password authentication. # # Taken by itself, #bind can be used to authenticate a user against information # stored in a directory, for example to permit or deny access to some other resource. # In terms of the other LDAP operations, most directories require a successful #bind to # be performed before the other operations will be permitted. Some servers permit certain # operations to be performed with an "anonymous" binding, meaning that no credentials are # presented by the user. (We're glossing over a lot of platform-specific detail here.) # # ==== Search # Calling #search against the directory involves specifying a treebase, a set of search filters, # and a list of attribute values. # The filters specify ranges of possible values for particular attributes. Multiple # filters can be joined together with AND, OR, and NOT operators. # A server will respond to a #search by returning a list of matching DNs together with a # set of attribute values for each entity, depending on what attributes the search requested. # # ==== Add # #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 # #modify specifies an entity DN, and a list of attribute operations. #modify is used to change # 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. # Net::LDAP provides three easier methods to modify an entry's attribute values: # #add_attribute, #replace_attribute, and #delete_attribute. # # ==== Delete # #delete specifies an entity DN. If it succeeds, the entity and all its attributes # is removed from the directory. # # ==== Rename (or Modify RDN) # #rename (or #modify_rdn) is an operation added to version 3 of the LDAP protocol. It responds to # the often-arising need to change the DN of an entity without discarding its attribute values. # In earlier LDAP versions, the only way to do this was to delete the whole entity and add it # again with a different DN. # # #rename works by taking an "old" DN (the one to change) and a "new RDN," which is the left-most # part of the DN string. If successful, #rename changes the entity DN so that its left-most # node corresponds to the new RDN given in the request. (RDN, or "relative distinguished name," # denotes a single tree-node as expressed in a DN, which is a chain of tree nodes.) # # == How to use Net::LDAP # # To access Net::LDAP functionality in your Ruby programs, start by requiring # the library: # # require 'net/ldap' # # If you installed the Gem version of Net::LDAP, and depending on your version of # Ruby and rubygems, you _may_ also need to require rubygems explicitly: # # require 'rubygems' # require 'net/ldap' # # Most operations with Net::LDAP start by instantiating a Net::LDAP object. # The constructor for this object takes arguments specifying the network location # (address and port) of the LDAP server, and also the binding (authentication) # credentials, typically a username and password. # Given an object of class Net:LDAP, you can then perform LDAP operations by calling # instance methods on the object. These are documented with usage examples below. # # The Net::LDAP library is designed to be very disciplined about how it makes network # connections to servers. This is different from many of the standard native-code # libraries that are provided on most platforms, which share bloodlines with the # original Netscape/Michigan LDAP client implementations. These libraries sought to # insulate user code from the workings of the network. This is a good idea of course, # but the practical effect has been confusing and many difficult bugs have been caused # by the opacity of the native libraries, and their variable behavior across platforms. # # In general, Net::LDAP instance methods which invoke server operations make a connection # to the server when the method is called. They execute the operation (typically binding first) # and then disconnect from the server. The exception is Net::LDAP#open, which makes a connection # to the server and then keeps it open while it executes a user-supplied block. Net::LDAP#open # closes the connection on completion of the block. # class LDAP class LdapError < Exception; end VERSION = "0.0.2" SearchScope_BaseObject = 0 SearchScope_SingleLevel = 1 SearchScope_WholeSubtree = 2 SearchScopes = [SearchScope_BaseObject, SearchScope_SingleLevel, SearchScope_WholeSubtree] AsnSyntax = { :application => { :constructed => { 0 => :array, # BindRequest 1 => :array, # BindResponse 2 => :array, # UnbindRequest 3 => :array, # SearchRequest 4 => :array, # SearchData 5 => :array, # SearchResult 6 => :array, # ModifyRequest 7 => :array, # ModifyResponse 8 => :array, # AddRequest 9 => :array, # AddResponse 10 => :array, # DelRequest 11 => :array, # DelResponse 12 => :array, # ModifyRdnRequest 13 => :array, # ModifyRdnResponse 14 => :array, # CompareRequest 15 => :array, # CompareResponse 16 => :array, # AbandonRequest 24 => :array, # Unsolicited Notification } }, :context_specific => { :primitive => { 0 => :string, # password 1 => :string, # Kerberos v4 2 => :string, # Kerberos v5 }, :constructed => { 0 => :array, # RFC-2251 Control } } } DefaultHost = "127.0.0.1" DefaultPort = 389 DefaultAuth = {:method => :anonymous} 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", 32 => "No Such Object", 34 => "Invalid DN Syntax", 48 => "Invalid DN Syntax", 48 => "Inappropriate Authentication", 49 => "Invalid Credentials", 50 => "Insufficient Access Rights", 51 => "Busy", 52 => "Unavailable", 53 => "Unwilling to perform", 65 => "Object Class Violation", 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 # :nodoc: ResultStrings[code] || "unknown result (#{code})" end # Instantiate an object of type Net::LDAP to perform directory operations. # This constructor takes a Hash containing arguments. The following arguments # are supported: # * :host => the LDAP server's IP-address (default 127.0.0.1) # * :port => the LDAP server's TCP port (default 389) # * :auth => a Hash containing authorization parameters. Currently supported values include: # {:method => :anonymous} and # {:method => :simple, :username => your_user_name, :password => your_password } # # Instantiating a Net::LDAP object does not result in network traffic to # the LDAP server. It simply stores the connection and binding parameters in the # object. # def initialize args = {} @host = args[:host] || DefaultHost @port = args[:port] || DefaultPort @verbose = false # Make this configurable with a switch on the class. @auth = args[:auth] || DefaultAuth # This variable is only set when we are created with LDAP::open. # All of our internal methods will connect using it, or else # they will create their own. @open_connection = nil end # #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 # perform operations against the LDAP directory. #open will perform all the # operations in the user-supplied block on the same network connection, which # will be closed automatically when the block finishes. # # # (PSEUDOCODE) # auth = {:method => :simple, :username => username, :password => password} # Net::LDAP.open( :host => ipaddress, :port => 389, :auth => auth ) do |ldap| # ldap.search( ... ) # ldap.add( ... ) # ldap.modify( ... ) # end # def LDAP::open args ldap1 = LDAP.new args ldap1.open {|ldap| yield ldap } end # Returns a meaningful result any time after # a protocol operation (#bind, #search, #add, #modify, #rename, #delete) # has completed. # It returns an #OpenStruct containing an LDAP result code (0 means success), # and a human-readable string. # unless ldap.bind # puts "Result: #{ldap.get_operation_result.code}" # puts "Message: #{ldap.get_operation_result.message}" # end # def get_operation_result os = OpenStruct.new if @result os.code = @result else os.code = 0 end os.message = LDAP.result2string( os.code ) os end # Opens a network connection to the server and then # passes self to the caller-supplied block. The connection is # closed when the block completes. Used for executing multiple # LDAP operations without requiring a separate network connection # (and authentication) for each one. # Note: You do not need to log-in or "bind" to the server. This will # be done for you automatically. # For an even simpler approach, see the class method Net::LDAP#open. # # # (PSEUDOCODE) # auth = {:method => :simple, :username => username, :password => password} # ldap = Net::LDAP.new( :host => ipaddress, :port => 389, :auth => auth ) # ldap.open do |ldap| # ldap.search( ... ) # ldap.add( ... ) # ldap.modify( ... ) # end #-- # First we make a connection and then a binding, but we don't # do anything with the bind results. # We then pass self to the caller's block, where he will execute # his LDAP operations. Of course they will all generate auth failures # if the bind was unsuccessful. def open raise LdapError.new( "open already in progress" ) if @open_connection @open_connection = Connection.new( :host => @host, :port => @port ) @open_connection.bind @auth yield self @open_connection.close end # DEPRECATED. 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); # * :filter (an object of type Net::LDAP::Filter, defaults to objectclass=*); # * :attributes (a string or array of strings specifying the LDAP attributes to return from the server); # * :return_result (a boolean specifying whether to return a result set). # * :attributes_only (a boolean flag, defaults false) # * :scope (one of: Net::LDAP::SearchScope_BaseObject, Net::LDAP::SearchScope_SingleLevel, Net::LDAP::SearchScope_WholeSubtree. Default is WholeSubtree.) # # #search queries the LDAP server and passes each entry to the # caller-supplied block, as an object of type Net::LDAP::Entry. # If the search returns 1000 entries, the block will # be called 1000 times. If the search returns no entries, the block will # not be called. # # #search returns either a result-set or a boolean, depending on the # value of the :return_result argument. The default behavior is to return # a result set, which is a hash. Each key in the hash is a string specifying # the DN of an entry. The corresponding value for each key is a Net::LDAP::Entry object. # 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 :return_result => false, #search will # return only a Boolean, to indicate whether the operation succeeded. This can improve performance # with very large result sets, because the library can discard each entry from memory after # your block processes it. # # # treebase = "dc=example,dc=com" # filter = Net::LDAP::Filter.eq( "mail", "a*.com" ) # attrs = ["mail", "cn", "sn", "objectclass"] # ldap.search( :base => treebase, :filter => filter, :attributes => attrs, :return_result => false ) do |entry| # puts "DN: #{entry.dn}" # entry.each do |attr, values| # puts ".......#{attr}:" # values.each do |value| # puts " #{value}" # end # end # end # #-- # This is a re-implementation of search that replaces the # original one (now renamed searchx and possibly destined to go away). # The difference is that we return a dataset (or nil) from the # call, and pass _each entry_ as it is received from the server # to the caller-supplied block. This will probably make things # far faster as we can do useful work during the network latency # of the search. The downside is that we have no access to the # whole set while processing the blocks, so we can't do stuff # like sort the DNs until after the call completes. # It's also possible that this interacts badly with server timeouts. # We'll have to ensure that something reasonable happens if # the caller has processed half a result set when we throw a timeout # error. # Another important difference is that we return a result set from # this method rather than a T/F indication. # Since this can be very heavy-weight, we define an argument flag # 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 : {} if @open_connection @result = @open_connection.search( args ) {|entry| result_set[entry.dn] = entry if result_set yield( entry ) if block_given? } else @result = 0 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 yield( entry ) if block_given? } end conn.close end @result == 0 and result_set end # #bind connects to the LDAP server and requests authentication # based on the :auth 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. #-- # If there is an @open_connection, then perform the bind # on it. Otherwise, connect, bind, and disconnect. # The latter operation is obviously useful only as an auth check. # def bind if @open_connection @result = @open_connection.bind @auth else conn = Connection.new( :host => @host, :port => @port ) @result = conn.bind @auth conn.close end @result == 0 end # # #bind_as is for testing authentication credentials. # Most likely a "standard" name (like a CN or an email # address) will be presented along with a password. # We'll bind with the main credential given in the # constructor, query the full DN of the user given # to us as a parameter, then unbind and rebind as the # new user. # # This method is currently an unimplemented stub. # def bind_as end # Adds a new entry to the remote LDAP server. # Supported arguments: # :dn :: Full DN of the new entry # :attributes :: Attributes of the new entry. # # The attributes argument is supplied as a Hash keyed by Strings or Symbols # giving the attribute name, and mapping to Strings or Arrays of Strings # giving the actual attribute values. Observe that most LDAP directories # enforce schema constraints on the attributes contained in entries. # #add will fail with a server-generated error if your attributes violate # the server-specific constraints. # Here's an example: # # dn = "cn=George Smith,ou=people,dc=example,dc=com" # attr = { # :cn => "George Smith", # :objectclass => ["top", "inetorgperson"], # :sn => "Smith", # :mail => "gsmith@example.com" # } # Net::LDAP.open (:host => host) do |ldap| # ldap.add( :dn => dn, :attributes => attr ) # end # def add args if @open_connection @result = @open_connection.add( args ) else @result = 0 conn = Connection.new( :host => @host, :port => @port ) if (@result = conn.bind( args[:auth] || @auth )) == 0 @result = conn.add( args ) end conn.close end @result == 0 end # _DEPRECATED_ - Please use #add_attribute, #replace_attribute, or #delete_attribute. # # Modifies the attribute values of a particular entry on the LDAP directory. # Takes a hash with arguments. Supported arguments are: # :dn :: (the full DN of the entry whose attributes are to be modified) # :operations :: (the modifications to be performed, detailed next) # # This method returns True or False to indicate whether the operation # succeeded or failed, with extended information available by calling # #get_operation_result. # # The LDAP protocol provides a full and well thought-out set of operations # for changing the values of attributes, but they are necessarily somewhat complex # and not always intuitive. If these instructions are confusing or incomplete, # please send us email or create a bug report on rubyforge. # # The :operations parameter to #modify takes an array of operation-descriptors. # Each individual operation is specified in one element of the array, and # most LDAP servers will attempt to perform the operations in order. # # Each of the operations appearing in the Array must itself be an Array # with exactly three elements: # an operator:: must be :add, :replace, or :delete # an attribute name:: the attribute name (string or symbol) to modify # a value:: either a string or an array of strings. # # The :add operator will, unsurprisingly, add the specified values to # the specified attribute. If the attribute does not already exist, # :add will create it. Most LDAP servers will generate an error if you # to add a value that already exists. # # :replace will erase the current value(s) for the specified attribute, # if there are any, and replace them with the specified value(s). # # :delete will remove the specified value(s) from the specified attribute. # If you pass nil, an empty string, or an empty array as the value parameter # to a :delete operation, the _entire_ _attribute_ will be deleted. # # For example: # # dn = "mail=modifyme@example.com,ou=people,dc=example,dc=com" # ops = [ # [:add, :mail, "aliasaddress@example.com"], # [:replace, :mail, ["newaddress@example.com", "newalias@example.com"]], # [:delete, :sn, nil] # ] # ldap.modify :dn => dn, :operations => ops # # (This example is contrived since you probably wouldn't add a mail # value right before replacing the whole attribute, but it shows that order # of execution matters. Also, many LDAP servers won't let you delete SN # because it would be a schema violation.) # # It's essential to keep in mind that if you specify more than one operation in # a call to #modify, most LDAP servers will attempt to perform all of the operations # in the order you gave them. # This matters because you may specify operations on the # same attribute which must be performed in a certain order. # Most LDAP servers will _stop_ processing your modifications if one of them # causes an error on the server (such as a schema-constraint violation). # If this happens, you will probably get a result code from the server that # reflects only the operation that failed, and you may or may not get extended # information that will tell you which one failed. #modify has no notion # of an atomic transaction. If you specify a chain of modifications in one # call to #modify, and one of them fails, the preceding ones will usually # not be "rolled back," resulting in a partial update. This is a limitation # of the LDAP protocol, not of Net::LDAP. # # def modify args if @open_connection @result = @open_connection.modify( args ) else @result = 0 conn = Connection.new( :host => @host, :port => @port ) if (@result = conn.bind( args[:auth] || @auth )) == 0 @result = conn.modify( args ) end conn.close end @result == 0 end # Add a value to an attribute. # Takes the full DN of the entry to modify, # the name (Symbol or String) of the attribute, and the value (String or # Array). If the attribute does not exist (and there are no schema violations), # #add_attribute will create it with the caller-specified values. # If the attribute already exists (and there are no schema violations), the # caller-specified values will be _added_ to the values already present. # # Returns True or False to indicate whether the operation # succeeded or failed, with extended information available by calling # #get_operation_result. See also #replace_attribute and #delete_attribute. # # dn = "cn=modifyme,dc=example,dc=com" # ldap.add_attribute dn, :mail, "newmailaddress@example.com" # def add_attribute dn, attribute, value modify :dn => dn, :operations => [[:add, attribute, value]] end # Replace the value of an attribute. # #replace_attribute can be thought of as equivalent to calling #delete_attribute # followed by #add_attribute. It takes the full DN of the entry to modify, # the name (Symbol or String) of the attribute, and the value (String or # Array). If the attribute does not exist, it will be created with the # caller-specified value(s). If the attribute does exist, its values will be # _discarded_ and replaced with the caller-specified values. # # Returns True or False to indicate whether the operation # succeeded or failed, with extended information available by calling # #get_operation_result. See also #add_attribute and #delete_attribute. # # dn = "cn=modifyme,dc=example,dc=com" # ldap.replace_attribute dn, :mail, "newmailaddress@example.com" # def replace_attribute dn, attribute, value modify :dn => dn, :operations => [[:replace, attribute, value]] end # Delete an attribute and all its values. # Takes the full DN of the entry to modify, and the # name (Symbol or String) of the attribute to delete. # # Returns True or False to indicate whether the operation # succeeded or failed, with extended information available by calling # #get_operation_result. See also #add_attribute and #replace_attribute. # # dn = "cn=modifyme,dc=example,dc=com" # ldap.delete_attribute dn, :mail # def delete_attribute dn, attribute modify :dn => dn, :operations => [[:delete, attribute, nil]] end # Rename an entry on the remote DIS by changing the last RDN of its DN. # _Documentation_ _stub_ # def rename args if @open_connection @result = @open_connection.rename( args ) else @result = 0 conn = Connection.new( :host => @host, :port => @port ) if (@result = conn.bind( args[:auth] || @auth )) == 0 @result = conn.rename( args ) end conn.close end @result == 0 end # modify_rdn is an alias for #rename. def modify_rdn args rename args end # Delete an entry from the LDAP directory. # Takes a hash of arguments. # The only supported argument is :dn, which must # give the complete DN of the entry to be deleted. # Returns True or False to indicate whether the delete # succeeded. Extended status information is available by # calling #get_operation_result. # # dn = "mail=deleteme@example.com,ou=people,dc=example,dc=com" # ldap.delete :dn => dn # def delete args if @open_connection @result = @open_connection.delete( args ) else @result = 0 conn = Connection.new( :host => @host, :port => @port ) if (@result = conn.bind( args[:auth] || @auth )) == 0 @result = conn.delete( args ) end conn.close end @result == 0 end end # class LDAP class LDAP # This is a private class used internally by the library. It should not be called by user code. class Connection # :nodoc: LdapVersion = 3 #-- # initialize # def initialize server begin @conn = TCPsocket.new( server[:host], server[:port] ) rescue raise LdapError.new( "no connection to server" ) end yield self if block_given? end #-- # close # This is provided as a convenience method to make # sure a connection object gets closed without waiting # for a GC to happen. Clients shouldn't have to call it, # but perhaps it will come in handy someday. def close @conn.close @conn = nil end #-- # next_msgid # def next_msgid @msgid ||= 0 @msgid += 1 end #-- # bind # def bind auth user,psw = case auth[:method] when :anonymous ["",""] when :simple [auth[:username] || auth[:dn], auth[:password]] end raise LdapError.new( "invalid binding information" ) unless (user && psw) msgid = next_msgid.to_ber request = [LdapVersion.to_ber, user.to_ber, psw.to_ber_contextspecific(0)].to_ber_appsequence(0) request_pkt = [msgid, request].to_ber_sequence @conn.write request_pkt (be = @conn.read_ber(AsnSyntax) and pdu = Net::LdapPdu.new( be )) or raise LdapError.new( "no bind result" ) pdu.result_code end #-- # search # Alternate implementation, this yields each search entry to the caller # as it are received. # 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 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} 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) rfc2696_cookie = [739, ""] # size-limit is a funky number so we can distinguish it from errors. result_code = 0 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 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 # 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 result_code end #-- # 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 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 # TODO, need to support a time limit, in case the server fails to respond. # TODO!!! We're throwing an exception here on empty DN. # Should return a proper error instead, probaby from farther up the chain. # TODO!!! If the user specifies a bogus opcode, we'll throw a # confusing error here ("to_ber_enumerated is not defined on nil"). # def modify args modify_dn = args[:dn] or raise "Unable to modify empty DN" modify_ops = [] a = args[:operations] and a.each {|op, attr, values| # TODO, fix the following line, which gives a bogus error # if the opcode is invalid. op_1 = {:add => 0, :delete => 1, :replace => 2} [op.to_sym].to_ber_enumerated modify_ops << [op_1, [attr.to_s.to_ber, values.to_a.map {|v| v.to_ber}.to_ber_set].to_ber_sequence].to_ber_sequence } request = [modify_dn.to_ber, modify_ops.to_ber_sequence].to_ber_appsequence(6) pkt = [next_msgid.to_ber, request].to_ber_sequence @conn.write pkt (be = @conn.read_ber(AsnSyntax)) && (pdu = LdapPdu.new( be )) && (pdu.app_tag == 7) or raise LdapError.new( "response missing or invalid" ) pdu.result_code end #-- # add # TODO, need to support a time limit, in case the server fails to respond. # def add args add_dn = args[:dn] or raise LdapError.new("Unable to add empty DN") add_attrs = [] a = args[:attributes] and a.each {|k,v| add_attrs << [ k.to_s.to_ber, v.to_a.map {|m| m.to_ber}.to_ber_set ].to_ber_sequence } request = [add_dn.to_ber, add_attrs.to_ber_sequence].to_ber_appsequence(8) pkt = [next_msgid.to_ber, request].to_ber_sequence @conn.write pkt (be = @conn.read_ber(AsnSyntax)) && (pdu = LdapPdu.new( be )) && (pdu.app_tag == 9) or raise LdapError.new( "response missing or invalid" ) pdu.result_code end #-- # rename # TODO, need to support a time limit, in case the server fails to respond. # def rename args old_dn = args[:olddn] or raise "Unable to rename empty DN" new_rdn = args[:newrdn] or raise "Unable to rename to empty RDN" delete_attrs = args[:delete_attributes] ? true : false request = [old_dn.to_ber, new_rdn.to_ber, delete_attrs.to_ber].to_ber_appsequence(12) pkt = [next_msgid.to_ber, request].to_ber_sequence @conn.write pkt (be = @conn.read_ber(AsnSyntax)) && (pdu = LdapPdu.new( be )) && (pdu.app_tag == 13) or raise LdapError.new( "response missing or invalid" ) pdu.result_code end #-- # delete # TODO, need to support a time limit, in case the server fails to respond. # def delete args dn = args[:dn] or raise "Unable to delete empty DN" request = dn.to_s.to_ber_application_string(10) pkt = [next_msgid.to_ber, request].to_ber_sequence @conn.write pkt (be = @conn.read_ber(AsnSyntax)) && (pdu = LdapPdu.new( be )) && (pdu.app_tag == 11) or raise LdapError.new( "response missing or invalid" ) pdu.result_code end end # class Connection end # class LDAP end # module Net