ruby-activeldap 0.4.1

data/lib/activeldap/base.rb

@@ -0,0 +1,1094 @@
+# === 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
+
+
+  # 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::FATAL
+        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 nil
+    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 = nil
+    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(dnval)")
+          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
+      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
+            matches.push(eval("#{real_klass}.new(dnval)"))
+          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
+    # instance variables. initialize2() must be called to complete
+    # 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
+    def initialize(val='')
+      if val.class != String
+        raise TypeError, "Object key must be a String"
+      end
+      # 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
+
+      @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
+      @must = {} # list of schema required attributes
+      @may = {} # list of schema optional attributes
+      @sup = {} # list of schema supplemental attributes
+
+      # 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(: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
+            m.attrs.each do |attr|
+              # Load with subtypes just like @data
+              safe_attr, value = make_subtypes(attr, m.vals(attr).dup)
+              @ldap_data[safe_attr] = value
+            end
+          end
+          @exists = true
+          # Populate schema data
+          send(: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])
+          end
+
+        rescue LDAP::ResultError
+          @exists = false
+          # Create what should be the authoritative DN
+          @dn = "#{dnattr()}=#{val},#{base()}"
+          send(:objectClass=, required_classes())
+
+          # Setup dn attribute (later rdn too!)
+          attr_sym = "#{dnattr()}=".to_sym
+          send(attr_sym, val)
+        end
+      end
+    end # initialize2
+
+    # 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
+      return @attr_methods.keys
+    end
+
+    # 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 objectClass=(val)
+      if val.class != Array
+        raise TypeError, 'objectClass must be an Array'
+      end
+
+      val.each do |klass|
+        unless klass.class == String
+          raise TypeError, "Value in array is not a String. (#{klass.class})"
+        end
+        unless Base.schema.names("objectClasses").member? klass
+          # TODO MAKE OWN EXCEPTION
+          raise RuntimeError, "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 val.member? oc
+          raise "'#{oc}' must be a defined objectClass for class '#{self.class}'"
+        end
+      end
+
+      # Set the actual objectClass data
+      define_attribute_methods('objectClass')
+      @data['objectClass'] = val.uniq
+
+      # Build |data| from schema
+      # clear attr_method mapping first
+      @attr_methods = {}
+      @must = {}
+      @may = {}
+      @sup = {}
+      val.each do |objc|
+        # Setup dependencies for validation pre-save
+        @must[objc] = Base.schema.attr('objectClasses', objc, 'MUST')
+        @may[objc] = Base.schema.attr('objectClasses', objc, 'MAY')
+        @sup[objc] = Base.schema.attr('objectClasses', objc, 'SUP')
+        @must[objc] = [] if @must[objc].nil?
+        @may[objc] = [] if @may[objc].nil?
+        @sup[objc] = [] if @sup[objc].nil?
+
+        # setup the alias/attr method mapping for @must
+        @must[objc].each do |attr|
+          # Update attr_method with appropriate
+          define_attribute_methods(attr)
+        end
+
+        # setup the alias/attr method mapping for @may
+        @may[objc].each do |attr|
+          define_attribute_methods(attr)
+        end
+      end
+
+      # Delete all now invalid 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
+
+    # exists?
+    #
+    # Return whether the entry exists in LDAP or not
+    def exists?
+      return @exists
+    end
+
+    # dn
+    #
+    # Return the authoritative dn
+    def dn
+      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
+    def validate
+      @must.each do |oc|
+         oc[1].each do |req_attr|
+          # TODO: should I ever check if key exists? bug if it doesnt...
+          deref = @attr_methods[req_attr]
+          if @data[deref] == []
+            raise AttributeEmpty,
+              "objectClass '#{oc[0]}' requires attribute '#{Base.schema.attribute_aliases(req_attr).join(', ')}'"
+          end
+        end
+      end
+    end
+
+
+    # delete
+    #
+    # Delete this entry from LDAP
+    def delete
+      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
+      # Validate against the objectClass requirements
+      validate
+
+      # Put all changes into one change entry to ensure
+      # automatic rollback upon failure.
+      entry = []
+      if @exists
+        # Cycle through all attrs to determine action
+        action = {}
+
+        replaceable = []
+
+        # Expand subtypes to real ldap_data entries
+        # We can't reuse @ldap_data because an exception would leave
+        # an object in an unknown state
+        ldap_data = @ldap_data.dup
+        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
+
+        # Expand subtypes to real data entries, but leave @data alone
+        data = @data.dup
+        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
+
+        # 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.
+        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 suffix.match(/;binary(;|$)/)
+
+          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
+        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 suffix.match(/;binary(;|$)/)
+            @@logger.debug("adding attribute to existing entry:  #{name+suffix}: #{value.inspect}")
+            entry.push(LDAP.mod(LDAP::LDAP_MOD_ADD|binary, name + suffix, value)) unless value.empty?
+          end
+        end
+        begin
+          @@conn.modify(@dn, entry)
+        rescue => detail
+          raise WriteError, "Could not update LDAP entry: #{detail}"
+        end
+      else # add everything!
+        entry.push(LDAP.mod(LDAP::LDAP_MOD_ADD, @attr_methods[dnattr()], 
+          data[@attr_methods[dnattr()]]))
+        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
+            binary = LDAP::LDAP_MOD_BVALUES if pair[0].match(/;binary(;|$)/)
+            @@logger.debug("adding attribute to new entry:  #{name+suffix}: #{value.inspect}")
+            entry.push(LDAP.mod(LDAP::LDAP_MOD_ADD|binary, pair[0], pair[1]))
+          end
+        end
+        begin
+          @@conn.add(@dn, entry)
+          @exists = true
+        rescue LDAP::ResultError => detail
+          raise WriteError, "Could not add LDAP entry: #{detail}"
+        end
+      end
+      @ldap_data = @data.dup
+    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)
+      key = name.to_s
+      case key
+        when /^(\S+)=$/
+          real_key = $1
+          if @attr_methods.has_key? real_key
+            raise ArgumentError, "wrong number of arguments (#{args.size} for 1)" if args.size != 1
+            return send(:attribute_method=, real_key, args[0])
+          end
+        else
+          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
+
+
+     private
+
+     # Enforce typing:
+     # Hashes are for subtypes
+     # Arrays are for multiple entries
+     def attribute_input_handler(attr, value)
+       if attr.nil?
+         raise RuntimeError, 'attr argument must not be nil.'
+       end
+       binary = Base.schema.binary? attr
+       single = Base.schema.single_value? attr
+       case value.class.to_s
+         when 'Array'
+           if single and value.size > 1
+             raise TypeError, "This attribute can only have a single value"
+           end
+           value.map! do |entry|
+             entry = entry.to_s unless entry.class == Hash
+             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)
+      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)
+      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)
+      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
+       self.class.base
+     end
+
+     # required_classes
+     #
+     # Returns the value of self.class.required_classes
+     # This is just syntactic sugar
+     def required_classes
+       self.class.required_classes
+     end
+
+     # dnattr
+     #
+     # Returns the value of self.class.dnattr
+     # This is just syntactic sugar
+     def dnattr
+       self.class.dnattr
+     end
+
+     # attribute_method
+     #
+     # Return the value of the attribute called by method_missing?
+     def attribute_method(method, arrays = false)
+       attr = @attr_methods[method]
+
+       # Return a copy of the stored data
+       return @data[attr].dup if arrays
+       return array_of(@data[attr].dup, false)
+     end
+
+
+     # attribute_method=
+     #
+     # Set the value of the attribute called by method_missing?
+     def attribute_method=(method, arg)
+       # Copy input
+       begin
+         value = arg.dup
+       rescue TypeError
+         value = arg.to_s
+       end
+
+       # Get the attr and clean up the input
+       attr = @attr_methods[method]
+       value = attribute_input_handler(attr, value)
+
+       # Assign the value 
+       @data[attr] = value
+
+       # Return a copy of what got saved
+       return @data[attr].dup
+     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)
+       if @attr_methods.has_key? attr
+         return
+       end
+       aliases = Base.schema.attribute_aliases(attr)
+       aliases.each do |ali|
+         @attr_methods[ali] = attr
+       end
+     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)
+      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
+
+
+
+