ruby-activeldap-debug 0.5.5

data/lib/activeldap/base.rb

@@ -0,0 +1,1244 @@
+# === ActiveLDAP - an OO-interface to LDAP objects inspired by ActiveRecord
+# Author: Will Drewry <will@alum.bu.edu>
+# License: See LICENSE and COPYING.txt
+# Copyright 2004 Will Drewry <will@alum.bu.edu>
+#
+# == Summary
+# ActiveLDAP lets you read and update LDAP entries in a completely object
+# oriented fashion, even handling attributes with multiple names seamlessly.
+# It was inspired by ActiveRecord so extending it to deal with custom
+# LDAP schemas is as effortless as knowing the 'ou' of the objects, and the
+# primary key. (fix this up some)
+#
+# == Example
+#   irb> require 'activeldap'
+#   > true
+#   irb> user = ActiveLDAP::User.new("drewry")
+#   > #<ActiveLDAP::User:0x402e...
+#   irb> user.cn
+#   > "foo"
+#   irb> user.commonname
+#   > "foo"
+#   irb> user.cn = "Will Drewry"
+#   > "Will Drewry"
+#   irb> user.cn
+#   > "Will Drewry"
+#   irb> user.validate
+#   > nil
+#   irb> user.write
+#
+#
+
+require 'ldap'
+require 'ldap/schema'
+require 'log4r'
+
+module ActiveLDAP
+  # OO-interface to LDAP assuming pam/nss_ldap-style comanization with Active specifics
+  # Each subclass does a ldapsearch for the matching entry.
+  # If no exact match, raise an error.
+  # If match, change all LDAP attributes in accessor attributes on the object.
+  # -- these are ACTUALLY populated from schema - see subschema.rb example
+  # -- @conn.schema().each{|k,vs| vs.each{|v| print("#{k}: #{v}\n")}}
+  # -- extract objectClasses from match and populate
+  # Multiple entries become lists.
+  # If this isn't read-only then lists become multiple entries, etc.
+
+  # AttributeEmpty
+  #
+  # An exception raised when a required attribute is found to be empty
+  class AttributeEmpty < RuntimeError
+  end
+
+  # DeleteError
+  #
+  # An exception raised when an ActiveLDAP delete action fails
+  class DeleteError < RuntimeError
+  end
+
+  # WriteError
+  #
+  # An exception raised when an ActiveLDAP write action fails
+  class WriteError < RuntimeError
+  end
+
+  # AuthenticationError
+  #
+  # An exception raised when user authentication fails
+  class AuthenticationError < RuntimeError
+  end
+
+  # ConnectionError
+  #
+  # An exception raised when the LDAP conenction fails
+  class ConnectionError < RuntimeError
+  end
+
+  # ObjectClassError
+  #
+  # An exception raised when an objectClass is not defined in the schema
+  class ObjectClassError < RuntimeError
+  end
+
+
+  # Base
+  #
+  # Base is the primary class which contains all of the core
+  # ActiveLDAP functionality. It is meant to only ever be subclassed
+  # by extension classes.
+  class Base
+    # Parsed schema structures
+    attr_reader :must, :may
+    attr_accessor :logger
+
+    # All class-wide variables
+    @@config = nil # Container for current connection settings
+    @@schema = nil # LDAP server's schema
+    @@conn = nil # LDAP connection
+
+    # Driver generator
+    #
+    # TODO add type checking
+    # This let's you call this method to create top-level extension object. This
+    # is really just a proof of concept and has not truly useful purpose.
+    # example: Base.create_object(:class => "user", :dnattr => "uid", :classes => ['top'])
+    #
+    def Base.create_object(config={})
+      # Just upcase the first letter of the new class name
+      str = config[:class]
+      class_name = str[0].chr.upcase + str[1..-1]
+
+      attr = config[:dnattr] # "uid"
+      prefix = config[:base] # "ou=People"
+      # [ 'top', 'posixAccount' ]
+      classes_array = config[:classes] || []
+      # [ [ :groups, {:class_name => "Group", :foreign_key => "memberUid"}] ]
+      belongs_to_array = config[:belongs_to] || []
+      # [ [ :members, {:class_name => "User", :foreign_key => "uid", :local_key => "memberUid"}] ]
+      has_many_array = config[:has_many] || []
+
+      raise TypeError, ":objectclasses must be an array" unless classes_array.respond_to? :size
+      raise TypeError, ":belongs_to must be an array" unless belongs_to_array.respond_to? :size
+      raise TypeError, ":has_many must be an array" unless has_many_array.respond_to? :size
+
+      # Build classes array
+      classes = '['
+      classes_array.map! {|x| x = "'#{x}'"}
+      classes << classes_array.join(', ')
+      classes << ']'
+
+      # Build belongs_to
+      belongs_to = []
+      if belongs_to_array.size > 0
+        belongs_to_array.each do |bt|
+          line = [ "belongs_to :#{bt[0]}" ]
+          bt[1].keys.each do |key|
+            line << ":#{key} => '#{bt[1][key]}'"
+          end
+          belongs_to << line.join(', ')
+        end
+      end
+
+      # Build has_many
+      has_many = []
+      if has_many_array.size > 0
+        has_many_array.each do |hm|
+          line = [ "has_many :#{hm[0]}" ]
+          hm[1].keys.each do |key|
+            line << ":#{key} => '#{hm[1][key]}'"
+          end
+          has_many << line.join(', ')
+        end
+      end
+
+      self.class.module_eval <<-"end_eval"
+        class ::#{class_name} < ActiveLDAP::Base
+          ldap_mapping :dnattr => "#{attr}, :prefix => "#{prefix}", :classes => "#{classes}"
+          #{belongs_to.join("\n")}
+          #{has_many.join("\n")}
+        end
+      end_eval
+    end
+
+    # Connect and bind to LDAP creating a class variable for use by all ActiveLDAP
+    # objects.
+    # 
+    # == +config+
+    # +config+ must be a hash that may contain any of the following fields:
+    # :user, :password_block, :logger, :host, :port, :base, :bind_format, :try_sasl, :allow_anonymous
+    # :user specifies the username to bind with.
+    # :bind_format specifies the string to substitute the username into on bind.  e.g. uid=%s,ou=People,dc=example,dc=com. Overrides @@bind_format.
+    # :password_block specifies a Proc object that will yield a String to be used as the password when called.
+    # :logger specifies a preconfigured Log4r::Logger to be used for all logging
+    # :host overrides the configuration.rb @@host setting with the LDAP server hostname
+    # :port overrides the configuration.rb @@port setting for the LDAP server port
+    # :base overwrites Base.base - this affects EVERYTHING
+    # :try_sasl indicates that a SASL bind should be attempted when binding to the server (default: false)
+    # :allow_anonymous indicates that a true anonymous bind is allowed when trying to bind to the server (default: true)
+    def Base.connect(config={}) # :user, :password_block, :logger
+      # Process config
+      # Class options
+      ## These will be replace by configuration.rb defaults if defined
+      @@config = {}
+      @@config[:host] = config[:host] || @@host
+      @@config[:port] = config[:port] || @@port
+      if config[:base]
+        Base.class_eval <<-"end_eval"
+          def Base.base
+            '#{config[:base]}'
+          end
+        end_eval
+      end
+      @@config[:bind_format] = config[:bind_format] || @@bind_format
+
+      @@logger = config[:logger] || nil
+      # Setup default logger to console
+      if @@logger.nil?
+        @@logger = Log4r::Logger.new('activeldap')
+        @@logger.level = Log4r::OFF
+        Log4r::StderrOutputter.new 'console'
+        @@logger.add('console')
+      end
+
+      # Method options
+      user = nil
+      password_block = nil
+      @@config[:allow_anonymous] = true
+      @@config[:try_sasl] = false
+
+      @@config[:user] = config[:user] || user
+      @@config[:allow_anonymous] = config[:allow_anonymous] if config.has_key? :allow_anonymous
+      @@config[:try_sasl] = config[:try_sasl]
+      @@config[:password_block] = config[:password_block] if config.has_key? :password_block
+
+      # Setup bind credentials
+      @@config[:user] = ENV['USER'] unless @@config[:user]
+
+      # Connect to LDAP
+      begin
+        # SSL using START_TLS
+        @@conn = LDAP::SSLConn.new(@@config[:host], @@config[:port], true)
+      rescue
+        @@logger.warn "Warning: Failed to connect using TLS!"
+        begin
+          @@logger.warn "Warning: Attempting SSL connection . . ."
+          @@conn = LDAP::SSLConn.new(@@config[:host], @@config[:port], false)
+          # HACK: Load the schema here because otherwise you can't tell if the
+          # HACK: SSLConn is a real SSL connection.
+          @@schema = @@conn.schema() if @@schema.nil?
+        rescue
+          @@logger.warn "Warning: Attempting unencrypted connection . . ."
+          @@conn = LDAP::Conn.new(@@config[:host], @@config[:port])
+        end
+      end
+      @@logger.debug "Connected to #{@@config[:host]}:#{@@config[:port]}."
+
+      # Enforce LDAPv3
+      @@conn.set_option(LDAP::LDAP_OPT_PROTOCOL_VERSION, 3)
+
+      # Authenticate
+      do_bind
+
+      # Load Schema (if not straight SSL...)
+      begin
+        @@schema = @@conn.schema() if @@schema.nil?
+      rescue => detail
+        raise ConnectionError, "#{detail.exception} - LDAP connection failure, or server does not support schema queries."
+      end
+
+      # Cleanly return
+      return true
+    end # Base.connect
+
+    # Base.close
+    # This method deletes the LDAP connection object.
+    # This does NOT reset any overridden values from a Base.connect call.
+    def Base.close
+      @@conn.unbind unless @@conn.nil?
+      @@conn = nil
+      # Make sure it is cleaned up
+      ObjectSpace.garbage_collect
+    end
+
+    # Return the LDAP connection object currently in use
+    def Base.connection
+      return @@conn
+    end
+
+    # Set the LDAP connection avoiding Base.connect or multiplexing connections
+    def Base.connection=(conn)
+      @@conn = conn
+    end
+
+    # Return the schema object
+    def Base.schema
+      @@schema
+    end
+
+    # search
+    #
+    # Wraps Ruby/LDAP connection.search to make it easier to search for specific
+    # data without cracking open Base.connection
+    def Base.search(config={})
+      unless Base.connection
+        if @@config
+          ActiveLDAP::Base.connect(@@config)
+        else
+          ActiveLDAP::Base.connect
+        end
+      end
+
+      config[:filter] = 'objectClass=*' unless config.has_key? :filter
+      config[:attrs] = [] unless config.has_key? :attrs
+      config[:scope] = LDAP::LDAP_SCOPE_SUBTREE unless config.has_key? :scope
+      config[:base] = base() unless config.has_key? :base
+
+      values = []
+      config[:attrs] = config[:attrs].to_a # just in case
+
+      begin
+        @@conn.search(config[:base], config[:scope], config[:filter], config[:attrs])  do |m|
+          res = {}
+          res['dn'] = [m.dn.dup] # For consistency with the below
+          m.attrs.each do |attr|
+            if config[:attrs].member? attr or config[:attrs].empty?
+              res[attr] = m.vals(attr).dup
+            end
+          end
+          values.push(res)
+        end
+      rescue RuntimeError => detail
+        @@logger.debug "No matches for #{config[:filter]} and attrs #{config[:attrs]}"
+        # Do nothing on failure
+      end
+      return values
+    end
+
+    # find
+    #
+    # Finds the first match for value where |value| is the value of some 
+    # |field|, or the wildcard match. This is only useful for derived classes.
+    # usage: Subclass.find(:attribute => "cn", :value => "some*val", :objects => true)
+    #        Subclass.find('some*val')
+    #
+    def Base.find(config = {})
+      unless Base.connection
+        if @@config
+          ActiveLDAP::Base.connect(@@config)
+        else
+          ActiveLDAP::Base.connect
+        end
+      end
+
+      if self.class == Class
+        klass = self.ancestors[0].to_s.split(':').last
+        real_klass = self.ancestors[0]
+      else 
+        klass = self.class.to_s.split(':').last
+        real_klass = self.class
+      end
+
+      # Allow a single string argument
+      attr = dnattr()
+      objects = false
+      val = config
+      # Or a hash
+      if config.respond_to?"has_key?"
+        attr = config[:attribute] || dnattr()
+        val = config[:value] || '*'
+        objects = config[:objects]
+      end
+
+      matches = []
+
+      begin
+        # Get some attributes
+        @@conn.search(base(), LDAP::LDAP_SCOPE_SUBTREE, "(#{attr}=#{val})")  do |m|
+          # Extract the dnattr value
+          dnval = m.dn.split(/,/)[0].split(/=/)[1]
+
+          if objects
+            return eval("#{real_klass}.new(m)")
+          else
+            return dnval
+          end
+        end
+      rescue RuntimeError => detail
+        @@logger.debug "No matches for #{attr}=#{val}"
+        # Do nothing on failure
+      end
+      return nil
+    end
+    private_class_method :find
+
+
+    # find_all
+    #
+    # Finds all matches for value where |value| is the value of some 
+    # |field|, or the wildcard match. This is only useful for derived classes.
+    def Base.find_all(config = {})
+      unless Base.connection
+        if @@config
+          ActiveLDAP::Base.connect(@@config)
+        else
+          ActiveLDAP::Base.connect
+        end
+      end
+
+      if self.class == Class
+        real_klass = self.ancestors[0]
+      else 
+        real_klass = self.class
+      end
+
+      # Allow a single string argument
+      val = config
+      objects = false
+      # Or a hash
+      if config.respond_to?"has_key?"
+        attr = config[:attribute] || dnattr()
+        val = config[:value] || '*'
+        objects = config[:objects]
+      end
+
+      matches = []
+
+      begin
+        # Get some attributes
+        @@conn.search(base(), LDAP::LDAP_SCOPE_SUBTREE, "(#{attr}=#{val})")  do |m|
+          # Extract the dnattr value
+          dnval = m.dn.split(/,/)[0].split(/=/)[1]
+
+          if objects
+            matches.push(eval("#{real_klass}.new(m)"))
+          else
+            matches.push(dnval)
+          end
+        end
+      rescue RuntimeError => detail
+        #p @@conn.err2string(@@conn.err)
+        @@logger.debug "No matches for #{attr}=#{val}"
+        # Do nothing on failure
+      end
+      return matches
+    end
+    private_class_method :find_all
+
+    # Base.base
+    # 
+    # This method when included into Base provides
+    # an inheritable, overwritable configuration setting
+    #
+    # This should be a string with the base of the
+    # ldap server such as 'dc=example,dc=com', and
+    # it should be overwritten by including
+    # configuration.rb into this class.
+    # When subclassing, the specified prefix will be concatenated.
+    def Base.base
+      'dc=example,dc=com'
+    end
+
+    # Base.dnattr
+    #
+    # This is a placeholder for the class method that will
+    # be overridden on calling ldap_mapping in a subclass.
+    # Using a class method allows for clean inheritance from
+    # classes that already have a ldap_mapping.
+    def Base.dnattr
+     ''
+    end
+
+    # Base.required_classes
+    #
+    # This method when included into Base provides
+    # an inheritable, overwritable configuration setting
+    #
+    # The value should be the minimum required objectClasses
+    # to make an object in the LDAP server, or an empty array [].
+    # This should be overwritten by configuration.rb.
+    # Note that subclassing does not cause concatenation of
+    # arrays to occurs.
+    def Base.required_classes
+      []
+    end
+
+
+
+    ### All instance methods, etc
+
+    # new
+    #
+    # Creates a new instance of Base initializing all class and all
+    # initialization.  Defines local defaults. See examples If multiple values
+    # exist for dnattr, the first one put here will be authoritative 
+    # TODO: Add # support for relative distinguished names 
+    # val can be a dn attribute value, a full DN, or a LDAP::Entry.  The use
+    # with a LDAP::Entry is primarily meant for internal use by find and
+    # find_all.
+    def initialize(val='')
+      # Try a default connection if none made explicitly
+      unless Base.connection
+        # Use @@config if it has been prepopulated and the conn is down.
+        if @@config
+          ActiveLDAP::Base.connect(@@config)
+        else
+          ActiveLDAP::Base.connect
+        end
+      end
+      if val.class == LDAP::Entry
+        # Call import, which is basically initialize
+        # without accessing LDAP.
+        @@logger.debug "initialize: val is a LDAP::Entry - running import."
+        import(val)
+        return
+      end
+      if val.class != String
+        raise TypeError, "Object key must be a String"
+      end
+
+      @data = {} # where the r/w entry data is stored
+      @data.default = []
+      @ldap_data = {} # original ldap entry data
+      @ldap_data.default = []
+      @attr_methods = {} # list of valid method calls for attributes used for dereferencing
+
+      # Break val apart if it is a dn
+      if val.match(/^#{dnattr()}=([^,=]+),#{base()}$/i)
+        val = $1
+      elsif val.match(/[=,]/)
+        @@logger.info "initialize: Changing val from '#{val}' to '' because it doesn't match the DN."
+        val = ''
+      end
+
+      # Do a search - if it exists, pull all data and parse schema, if not, just set the hierarchical data
+      if val.empty?
+        @exists = false
+        # Setup what should eb authoritative
+        @dn = "#{dnattr()}=#{val},#{base()}"
+        send(:apply_objectclass, required_classes())
+      else # do a search then
+        # Search for the existing entry
+        begin
+          # Get some attributes
+          Base.connection.search("#{dnattr()}=#{val},#{base()}", LDAP::LDAP_SCOPE_SUBTREE, "objectClass=*")  do |m|
+            # Save DN
+            @dn = m.dn
+            # Load up data into tmp
+            @@logger.debug("loading entry: #{@dn}")
+            m.attrs.each do |attr|
+              # Load with subtypes just like @data
+              @@logger.debug("calling make_subtypes for m.vals(attr).dup")
+              safe_attr, value = make_subtypes(attr, m.vals(attr).dup)
+              @@logger.debug("finished make_subtypes for #{attr}")
+              # Add subtype to any existing values
+              if @ldap_data.has_key? safe_attr
+                value.each do |v|
+                  @ldap_data[safe_attr].push(v)
+                end
+              else
+                @ldap_data[safe_attr] = value
+              end
+            end
+          end
+          @exists = true
+          # Populate schema data
+          send(:apply_objectclass, @ldap_data['objectClass'])
+
+          # Populate real data now that we have the schema with aliases
+          @ldap_data.each do |pair|
+            send(:attribute_method=, pair[0], pair[1].dup)
+          end
+
+        rescue LDAP::ResultError
+          @exists = false
+          # Create what should be the authoritative DN
+          @dn = "#{dnattr()}=#{val},#{base()}"
+          send(:apply_objectclass, required_classes())
+
+          # Setup dn attribute (later rdn too!)
+          attr_sym = "#{dnattr()}=".to_sym
+          @@logger.debug("new: setting dnattr: #{dnattr()} = #{val}")
+          send(attr_sym, val)
+        end
+      end
+    end # initialize
+
+    # Hide new in Base
+    private_class_method :new
+
+    # attributes
+    #
+    # Return attribute methods so that a program can determine available
+    # attributes dynamically without schema awareness
+    def attributes
+      @@logger.debug("stub: attributes called")
+      send(:apply_objectclass, @data['objectClass']) if @data['objectClass'] != @last_oc
+      return @attr_methods.keys
+    end
+
+    # exists?
+    #
+    # Return whether the entry exists in LDAP or not
+    def exists?
+      @@logger.debug("stub: exists? called")
+      return @exists
+    end
+
+    # dn
+    #
+    # Return the authoritative dn
+    def dn
+      @@logger.debug("stub: dn called")
+      return @dn.dup
+    end
+
+    # validate
+    #
+    # Basic validation:
+    # - Verify that every 'MUST' specified in the schema has a value defined
+    # - Enforcement of undefined attributes is handled in the objectClass= method
+    # Must call enforce_types() first before enforcement can be guaranteed
+    def validate
+      @@logger.debug("stub: validate called")
+      # Clean up attr values, etc
+      send(:enforce_types)
+
+      # Validate objectclass settings
+      @data['objectClass'].each do |klass|
+        unless klass.class == String
+          raise TypeError, "Value in objectClass array is not a String. (#{klass.class}:#{klass.inspect})"
+        end
+        unless Base.schema.names("objectClasses").member? klass
+          raise ObjectClassError, "objectClass '#{klass}' unknown to LDAP server."
+        end
+      end
+
+      # make sure this doesn't drop any of the required objectclasses
+      required_classes().each do |oc|
+        unless @data['objectClass'].member? oc.to_s
+          raise ObjectClassError, "'#{oc}' must be a defined objectClass for class '#{self.class}' as set in the ldap_mapping"
+        end
+      end
+
+      # Make sure all MUST attributes have a value
+      @data['objectClass'].each do |objc|
+        @must.each do |req_attr|
+          deref = @attr_methods[req_attr]
+          if @data[deref] == []
+            raise AttributeEmpty,
+              "objectClass '#{objc}' requires attribute '#{Base.schema.attribute_aliases(req_attr).join(', ')}'"
+          end
+        end
+      end
+      @@logger.debug("stub: validate finished")
+    end
+
+
+    # delete
+    #
+    # Delete this entry from LDAP
+    def delete
+      @@logger.debug("stub: delete called")
+      begin
+        @@conn.delete(@dn)
+        @exists = false
+      rescue LDAP::ResultError => detail
+        raise DeleteError, "Failed to delete LDAP entry: '#{@dn}'"
+      end
+    end
+
+
+    # write
+    #
+    # Write and validate this object into LDAP
+    # either adding or replacing attributes
+    # TODO: Binary data support
+    # TODO: Relative DN support
+    def write
+      @@logger.debug("stub: write called")
+      # Validate against the objectClass requirements
+      validate
+
+      # Put all changes into one change entry to ensure
+      # automatic rollback upon failure.
+      entry = []
+
+
+      # Expand subtypes to real ldap_data entries
+      # We can't reuse @ldap_data because an exception would leave
+      # an object in an unknown state
+      @@logger.debug("#write: dup'ing @ldap_data")
+      ldap_data = @ldap_data.dup
+      @@logger.debug("#write: dup finished @ldap_data")
+      @@logger.debug("#write: expanding subtypes in @ldap_data")
+      ldap_data.keys.each do |key|
+        ldap_data[key].each do |value|
+          if value.class == Hash
+            suffix, real_value = extract_subtypes(value)
+            if ldap_data.has_key? key + suffix
+              ldap_data[key + suffix].push(real_value)
+            else
+              ldap_data[key + suffix] = real_value
+            end
+            ldap_data[key].delete(value)
+          end
+        end
+      end
+      @@logger.debug("#write: subtypes expanded for @ldap_data")
+
+      # Expand subtypes to real data entries, but leave @data alone
+      @@logger.debug("#write: dup'ing @data")
+      data = @data.dup
+      @@logger.debug("#write: finished dup'ing @data")
+      @@logger.debug("#write: expanding subtypes for @data")
+      data.keys.each do |key|
+        data[key].each do |value|
+          if value.class == Hash
+            suffix, real_value = extract_subtypes(value)
+            if data.has_key? key + suffix
+              data[key + suffix].push(real_value)
+            else
+              data[key + suffix] = real_value
+            end
+            data[key].delete(value)
+          end
+        end
+      end
+      @@logger.debug("#write: subtypes expanded for @data")
+
+
+      if @exists
+        # Cycle through all attrs to determine action
+        action = {}
+
+        replaceable = []
+        # Now that all the subtypes will be treated as unique attributes
+        # we can see what's changed and add anything that is brand-spankin'
+        # new.
+        @@logger.debug("#write: traversing ldap_data determining replaces and deletes")
+        ldap_data.each do |pair|
+          suffix = ''
+          binary = 0
+
+          name, *suffix_a = pair[0].split(/;/)
+          suffix = ';'+ suffix_a.join(';') if suffix_a.size > 0
+          name = @attr_methods[name]
+          name = pair[0].split(/;/)[0] if name.nil? # for objectClass, or removed vals
+          value = data[name+suffix]
+
+          # Detect subtypes and account for them
+          binary = LDAP::LDAP_MOD_BVALUES if Base.schema.binary? name
+
+          replaceable.push(name+suffix)
+          if pair[1] != value
+            # Create mod entries
+            if not value.empty?
+              # Ditched delete then replace because attribs with no equality match rules
+              # will fails
+              @@logger.debug("updating attribute of existing entry:  #{name+suffix}: #{value.inspect}")
+              entry.push(LDAP.mod(LDAP::LDAP_MOD_REPLACE|binary, name + suffix, value))
+            else
+              # Since some types do not have equality matching rules, delete doesn't work
+              # Replacing with nothing is equivalent.
+              @@logger.debug("removing attribute from existing entry:  #{name+suffix}")
+              entry.push(LDAP.mod(LDAP::LDAP_MOD_REPLACE|binary, name + suffix, []))
+            end
+          end
+        end
+        @@logger.debug("#write: finished traversing ldap_data")
+        @@logger.debug("#write: traversing data determining adds")
+        data.each do |pair|
+          suffix = ''
+          binary = 0
+
+          name, *suffix_a = pair[0].split(/;/)
+          suffix = ';' + suffix_a.join(';') if suffix_a.size > 0
+          name = @attr_methods[name]
+          name = pair[0].split(/;/)[0] if name.nil? # for obj class or removed vals
+          value = pair[1]
+
+          if not replaceable.member? name+suffix
+            # Detect subtypes and account for them
+            binary = LDAP::LDAP_MOD_BVALUES if Base.schema.binary? name
+            @@logger.debug("adding attribute to existing entry:  #{name+suffix}: #{value.inspect}")
+            # REPLACE will function like ADD, but doesn't hit EQUALITY problems
+            # TODO: Added equality(attr) to Schema2
+            entry.push(LDAP.mod(LDAP::LDAP_MOD_REPLACE|binary, name + suffix, value)) unless value.empty?
+          end
+        end
+        @@logger.debug("#write: traversing data complete")
+        begin
+          @@logger.debug("#write: modifying #{@dn}")
+          @@conn.modify(@dn, entry)
+          @@logger.debug("#write: modify successful")
+        rescue => detail
+          raise WriteError, "Could not update LDAP entry: #{detail}"
+        end
+      else # add everything!
+        @@logger.debug("#write: adding all attribute value pairs")
+        @@logger.debug("#write: adding #{@attr_methods[dnattr()].inspect} = #{data[@attr_methods[dnattr()]].inspect}")
+        entry.push(LDAP.mod(LDAP::LDAP_MOD_ADD, @attr_methods[dnattr()], 
+          data[@attr_methods[dnattr()]]))
+        @@logger.debug("#write: adding objectClass = #{data[@attr_methods['objectClass']].inspect}")
+        entry.push(LDAP.mod(LDAP::LDAP_MOD_ADD, 'objectClass', 
+          data[@attr_methods['objectClass']]))
+        data.each do |pair|
+          if pair[1].size > 0  and pair[0] != 'objectClass' and pair[0] != @attr_methods[dnattr()]
+            # Detect subtypes and account for them
+            if Base.schema.binary? pair[0].split(/;/)[0]
+              binary = LDAP::LDAP_MOD_BVALUES 
+            else
+              binary = 0
+            end
+            @@logger.debug("adding attribute to new entry:  #{pair[0].inspect}: #{pair[1].inspect}")
+            entry.push(LDAP.mod(LDAP::LDAP_MOD_ADD|binary, pair[0], pair[1]))
+          end
+        end
+        begin
+          @@logger.debug("#write: adding #{@dn}")
+          @@conn.add(@dn, entry)
+          @@logger.debug("#write: add successful")
+          @exists = true
+        rescue LDAP::ResultError => detail
+          raise WriteError, "Could not add LDAP entry[#{Base.connection.err2string(Base.connection.err)}]: #{detail}"
+        end
+      end
+      @@logger.debug("#write: resetting @ldap_data to a dup of @data")
+      @ldap_data = @data.dup
+      @@logger.debug("#write: @ldap_data reset complete")
+      @@logger.debug("stub: write exitted")
+    end
+
+
+    # method_missing
+    #
+    # If a given method matches an attribute or an attribute alias
+    # then call the appropriate method.
+    # TODO: Determine if it would be better to define each allowed method
+    #       using class_eval instead of using method_missing.  This would
+    #       give tab completion in irb.
+    def method_missing(name, *args)
+      @@logger.debug("stub: called method_missing(#{name.inspect}, #{args.inspect})")
+
+      # dynamically update the available attributes without requiring an
+      # explicit call. The cache 'last_oc' saves a lot of cpu time.
+      if @data['objectClass'] != @last_oc
+        @@logger.debug("method_missing(#{name.inspect}, #{args.inspect}): updating apply_objectclass(#{@data['objectClass'].inspect})")
+        send(:apply_objectclass, @data['objectClass'])
+      end
+      key = name.to_s
+      case key
+        when /^(\S+)=$/
+          real_key = $1
+          @@logger.debug("method_missing: attr_methods has_key? #{real_key}")
+          if @attr_methods.has_key? real_key
+            raise ArgumentError, "wrong number of arguments (#{args.size} for 1)" if args.size != 1
+            @@logger.debug("method_missing: calling :attribute_method=(#{real_key}, #{args[0]})")
+            return send(:attribute_method=, real_key, args[0])
+          end
+        else
+          @@logger.debug("method_missing: attr_methods has_key? #{key}")
+          if @attr_methods.has_key? key
+            raise ArgumentError, "wrong number of arguments (#{args.size} for 1)" if args.size > 1
+            return attribute_method(key, *args)
+          end
+      end
+      raise NoMethodError, "undefined method `#{key}' for #{self}"
+    end
+
+    # Add available attributes to the methods
+    alias_method :__methods, :methods
+    def methods
+      return __methods + attributes()
+    end
+
+
+     private
+
+      # import(LDAP::Entry)
+      #
+      # Overwrites an existing entry (usually called by new)
+      # with the data given in the data given in LDAP::Entry.
+      #
+      def import(entry=nil)
+        @@logger.debug("stub: import called")
+        if entry.class != LDAP::Entry
+          raise TypeError, "argument must be a LDAP::Entry"
+        end
+
+        @data = {} # where the r/w entry data is stored
+        @data.default = []
+        @ldap_data = {} # original ldap entry data
+        @ldap_data.default = []
+        @attr_methods = {} # list of valid method calls for attributes used for dereferencing
+
+        # Get some attributes
+        @dn = entry.dn
+        entry.attrs.each do |attr|
+          # Load with subtypes just like @data
+          @@logger.debug("calling make_subtypes for entry.vals(attr).dup")
+          safe_attr, value = make_subtypes(attr, entry.vals(attr).dup)
+          @@logger.debug("finished make_subtypes for #{attr}")
+          # Add subtype to any existing values
+          if @ldap_data.has_key? safe_attr
+            value.each do |v|
+              @ldap_data[safe_attr].push(v)
+            end
+          else
+            @ldap_data[safe_attr] = value
+          end
+        end
+        # Assume if we are importing it that it exists
+        @exists = true
+        # Populate schema data
+        send(:apply_objectclass, @ldap_data['objectClass'])
+
+        # Populate real data now that we have the schema with aliases
+        @ldap_data.each do |pair|
+          send(:attribute_method=, pair[0], pair[1].dup)
+        end
+      end # import
+
+      # enforce_types
+      #
+      # enforce_types applies your changes without attempting to write to LDAP. This means that
+      # if you set userCertificate to somebinary value, it will wrap it up correctly.
+      def enforce_types
+        @@logger.debug("stub: enforce_types called")
+        send(:apply_objectclass, @data['objectClass']) if @data['objectClass'] != @last_oc
+        # Enforce attribute value formatting
+        @data.keys.each do |key|
+          @data[key] = attribute_input_handler(key, @data[key])
+        end
+        @@logger.debug("stub: enforce_types done")
+        return true
+      end
+
+      # apply_objectclass
+      #
+      # objectClass= special case for updating appropriately
+      # This updates the objectClass entry in @data. It also
+      # updating all required and allowed attributes while
+      # removing defined attributes that are no longer valid
+      # given the new objectclasses.
+      def apply_objectclass(val)
+        @@logger.debug("stub: objectClass=(#{val.inspect}) called")
+        new_oc = val
+        new_oc = [val] if new_oc.class != Array
+        return new_oc if @last_oc == new_oc
+
+        # Store for caching purposes
+        @last_oc = new_oc.dup
+
+         # Set the actual objectClass data
+        define_attribute_methods('objectClass')
+        @data['objectClass'] = new_oc.uniq
+
+        # Build |data| from schema
+        # clear attr_method mapping first
+        @attr_methods = {}
+	@must = []
+	@may = []
+        new_oc.each do |objc|
+          # get all attributes for the class
+          attributes = Base.schema.class_attributes(objc.to_s)
+	  @must += attributes[:must]
+	  @may += attributes[:may]
+        end
+	@must.uniq!
+	@may.uniq!
+        (@must+@may).each do |attr|
+            # Update attr_method with appropriate
+            define_attribute_methods(attr)
+        end
+
+        # Delete all now innew_ocid attributes given the new objectClasses
+        @data.keys.each do |key|
+          # If it's not a proper aliased attribute, drop it
+          unless @attr_methods.has_key? key
+            @data.delete(key)
+          end
+        end
+      end
+
+
+
+     # Enforce typing:
+     # Hashes are for subtypes
+     # Arrays are for multiple entries
+     def attribute_input_handler(attr, value)
+       @@logger.debug("stub: called attribute_input_handler(#{attr.inspect}, #{value.inspect})")
+       if attr.nil?
+         raise RuntimeError, 'The first argument, attr, must not be nil. Please report this as a bug!'
+       end
+       binary = Base.schema.binary_required? attr
+       single = Base.schema.single_value? attr
+       case value.class.to_s
+         when 'Array'
+           if single and value.size > 1
+             raise TypeError, "Attribute #{attr} can only have a single value"
+           end
+           value.map! do |entry|
+             if entry.class != Hash
+               @@logger.debug("coercing value for #{attr} into a string because nested values exceeds a useful depth: #{entry.inspect} -> #{entry.to_s}")
+               entry = entry.to_s
+             end
+             entry = attribute_input_handler(attr, entry)[0]
+           end
+         when 'Hash'
+           if value.keys.size > 1
+              raise TypeError, "Hashes must have one key-value pair only."
+           end
+           unless value.keys[0].match(/^(lang-[a-z][a-z]*)|(binary)$/)
+             @@logger.warn("unknown subtype did not match lang-* or binary: #{value.keys[0]}")
+           end
+           # Contents MUST be a String or an Array
+           if value.keys[0] != 'binary' and binary
+             suffix, real_value = extract_subtypes(value)
+             value = make_subtypes(name + suffix + ';binary', real_value)
+           end
+           value = [value]
+         when 'String'
+           if binary
+             value = {'binary' => value}
+           end
+           return [value]
+         else
+           value = [value.to_s]
+       end
+       return value
+     end
+ 
+    # make_subtypes
+    #
+    # Makes the Hashized value from the full attributename
+    # e.g. userCertificate;binary => "some_bin"
+    #      becomes userCertificate => {"binary" => "some_bin"}
+    def make_subtypes(attr, value)
+      @@logger.debug("stub: called make_subtypes(#{attr.inspect}, #{value.inspect})")
+      return [attr, value] unless attr.match(/;/)
+
+      ret_attr, *subtypes = attr.split(/;/)
+      return [ret_attr, [make_subtypes_helper(subtypes, value)]]
+    end
+
+    # make_subtypes_helper
+    #
+    # This is a recursive function for building
+    # nested hashed from multi-subtyped values
+    def make_subtypes_helper(subtypes, value)
+      @@logger.debug("stub: called make_subtypes_helper(#{subtypes.inspect}, #{value.inspect})")
+      return value if subtypes.size == 0
+      return {subtypes[0] => make_subtypes_helper(subtypes[1..-1], value)}
+    end
+
+    # extract_subtypes
+    #
+    # Extracts all of the subtypes from a given set of nested hashes
+    # and returns the attribute suffix and the final true value
+    def extract_subtypes(value)
+      @@logger.debug("stub: called extract_subtypes(#{value.inspect})")
+      subtype = ''
+      ret_val = value
+      if value.class == Hash
+        subtype = ';' + value.keys[0]
+        ret_val = value[value.keys[0]]
+        subsubtype = ''
+        if ret_val.class == Hash
+          subsubtype, ret_val = extract_subtypes(ret_val)
+        end
+        subtype += subsubtype
+      end
+      ret_val = [ret_val] unless ret_val.class == Array
+      return subtype, ret_val
+    end
+
+
+     # Wrapper all bind activity
+     def Base.do_bind()
+       bind_dn = @@config[:bind_format] % [@@config[:user]]
+       if @@config[:password_block]
+         password = @@config[:password_block].call
+         @@config[:password_block] = Proc.new { password }
+       end
+
+       # Rough bind loop:
+       # Attempt 1: SASL if available
+       # Attempt 2: SIMPLE with credentials if password block
+       # Attempt 3: SIMPLE ANONYMOUS if 1 and 2 fail (or pwblock returns '')
+       auth = false
+       auth = do_sasl_bind(bind_dn) if @@config[:try_sasl]
+       auth = do_simple_bind(bind_dn) unless auth
+       auth = do_anonymous_bind(bind_dn) if not auth and @@config[:allow_anonymous]
+
+       unless auth
+         raise AuthenticationError, "All authentication mechanisms failed"
+       end
+       return auth
+     end
+
+ 
+     # Base.do_anonymous_bind
+     #
+     # Bind to LDAP with the given DN, but with no password. (anonymous!)
+     def Base.do_anonymous_bind(bind_dn)
+       @@logger.info "Attempting anonymous authentication"
+       begin
+         @@conn.bind()
+         return true
+       rescue
+         @@logger.debug "LDAP Error: #{@@conn.err2string(@@conn.err)}"
+         @@logger.warn "Warning: Anonymous authentication failed."
+         return false
+       end
+     end
+
+     # Base.do_simple_bind
+     #
+     # Bind to LDAP with the given DN and password_block.call()
+     def Base.do_simple_bind(bind_dn)
+       return false unless @@config[:password_block].respond_to? :call
+       begin
+         @@conn.bind(bind_dn, @@config[:password_block].call())
+         return true
+       rescue
+         @@logger.debug "LDAP Error: #{@@conn.err2string(@@conn.err)}"
+         @@logger.warn "Warning: SIMPLE authentication failed."
+         return false
+       end
+     end
+
+     # Base.do_sasl_bind
+     #
+     # Bind to LDAP with the given DN using any available SASL methods
+     def Base.do_sasl_bind(bind_dn)
+       # Get all SASL mechanisms
+       mechanisms = @@conn.root_dse[0]['supportedSASLMechanisms']
+       # Use GSSAPI if available
+       # Currently only GSSAPI is supported with Ruby/LDAP from
+       # http://caliban.com/files/redhat/RPMS/i386/ruby-ldap-0.8.2-4.i386.rpm
+       # TODO: Investigate further SASL support
+       if mechanisms.respond_to? :member? and mechanisms.member? 'GSSAPI'
+         begin
+           @@conn.sasl_bind(bind_dn, 'GSSAPI')
+           return true
+         rescue
+           @@logger.debug "LDAP Error: #{@@conn.err2string(@@conn.err)}"
+           @@logger.warn "Warning: SASL GSSAPI authentication failed."
+           return false
+         end
+       end
+       return false
+     end
+
+     # base
+     #
+     # Returns the value of self.class.base
+     # This is just syntactic sugar
+     def base
+       @@logger.debug("stub: called base")
+       self.class.base
+     end
+
+     # required_classes
+     #
+     # Returns the value of self.class.required_classes
+     # This is just syntactic sugar
+     def required_classes
+       @@logger.debug("stub: called required_classes")
+       self.class.required_classes
+     end
+
+     # dnattr
+     #
+     # Returns the value of self.class.dnattr
+     # This is just syntactic sugar
+     def dnattr
+       @@logger.debug("stub: called dnattr")
+       self.class.dnattr
+     end
+
+     # attribute_method
+     #
+     # Return the value of the attribute called by method_missing?
+     def attribute_method(method, not_array = false)
+       @@logger.debug("stub: called attribute_method(#{method.inspect}, #{not_array.inspect}")
+       attr = @attr_methods[method]
+
+       # Return a copy of the stored data
+       return array_of(@data[attr].dup, false) if not_array
+       return @data[attr]
+     end
+
+
+     # attribute_method=
+     #
+     # Set the value of the attribute called by method_missing?
+     def attribute_method=(method, value)
+       @@logger.debug("stub: called attribute_method=(#{method.inspect}, #{value.inspect})")
+       # Get the attr and clean up the input
+       attr = @attr_methods[method]
+       @@logger.debug("attribute_method=(#{method.inspect}, #{value.inspect}): method maps to #{attr}")
+
+       # Assign the value 
+       @data[attr] = value
+
+       # Return the passed in value
+       @@logger.debug("stub: exitting attribute_method=")
+       return @data[attr]
+     end
+
+    
+     # define_attribute_methods
+     #
+     # Make a method entry for _every_ alias of a valid attribute and map it
+     # onto the first attribute passed in.
+     def define_attribute_methods(attr)
+       @@logger.debug("stub: called define_attribute_methods(#{attr.inspect})")
+       if @attr_methods.has_key? attr
+         return
+       end
+       aliases = Base.schema.attribute_aliases(attr)
+       aliases.each do |ali|
+         @@logger.debug("associating #{ali} --> #{attr}")
+         @attr_methods[ali] = attr
+       end
+       @@logger.debug("stub: leaving define_attribute_methods(#{attr.inspect})")
+     end
+
+    # array_of
+    #
+    # Returns the array form of a value, or not an array if
+    # false is passed in.
+    def array_of(value, to_a = true)
+      @@logger.debug("stub: called array_of(#{value.inspect}, #{to_a.inspect})")
+      if to_a
+        case value.class.to_s
+          when 'Array'
+            return value
+          when 'Hash'
+            return [value]
+          else
+            return [value.to_s]
+        end
+      else
+        case value.class.to_s
+          when 'Array'
+            return nil if value.size == 0
+            return value[0] if value.size == 1
+            return value
+          when 'Hash'
+            return value
+          else
+            return value.to_s
+        end
+      end
+    end
+
+  end # Base
+
+end # ActiveLDAP
+
+
+
+