net-ldap-1 0.4.0

data/lib/net/ldap/dataset.rb

@@ -0,0 +1,154 @@
+# -*- ruby encoding: utf-8 -*-
+##
+# An LDAP Dataset. Used primarily as an intermediate format for converting
+# to and from LDIF strings and Net::LDAP::Entry objects.
+class Net::LDAP::Dataset < Hash
+  ##
+  # Dataset object comments.
+  attr_reader :comments
+
+  def initialize(*args, &block) # :nodoc:
+    super
+    @comments = []
+  end
+
+  ##
+  # Outputs an LDAP Dataset as an array of strings representing LDIF
+  # entries.
+  def to_ldif
+    ary = []
+    ary += @comments unless @comments.empty?
+    keys.sort.each do |dn|
+      ary << "dn: #{dn}"
+
+      attributes = self[dn].keys.map { |attr| attr.to_s }.sort
+      attributes.each do |attr|
+        self[dn][attr.to_sym].each do |value|
+          if attr == "userpassword" or value_is_binary?(value)
+            value = [value].pack("m").chomp.gsub(/\n/m, "\n ")
+            ary << "#{attr}:: #{value}"
+          else
+            ary << "#{attr}: #{value}"
+          end
+        end
+      end
+
+      ary << ""
+    end
+    block_given? and ary.each { |line| yield line}
+
+    ary
+  end
+
+  ##
+  # Outputs an LDAP Dataset as an LDIF string.
+  def to_ldif_string
+    to_ldif.join("\n")
+  end
+
+  ##
+  # Convert the parsed LDIF objects to Net::LDAP::Entry objects.
+  def to_entries
+    ary = []
+    keys.each do |dn|
+      entry = Net::LDAP::Entry.new(dn)
+      self[dn].each do |attr, value|
+        entry[attr] = value
+      end
+      ary << entry
+    end
+    ary
+  end
+
+  ##
+  # This is an internal convenience method to determine if a value requires
+  # base64-encoding before conversion to LDIF output. The standard approach
+  # in most LDAP tools is to check whether the value is a password, or if
+  # the first or last bytes are non-printable. Microsoft Active Directory,
+  # on the other hand, sometimes sends values that are binary in the middle.
+  #
+  # In the worst cases, this could be a nasty performance killer, which is
+  # why we handle the simplest cases first. Ideally, we would also test the
+  # first/last byte, but it's a bit harder to do this in a way that's
+  # compatible with both 1.8.6 and 1.8.7.
+  def value_is_binary?(value) # :nodoc:
+    value = value.to_s
+    return true if value[0] == ?: or value[0] == ?<
+    value.each_byte { |byte| return true if (byte < 32) || (byte > 126) }
+    false
+  end
+  private :value_is_binary?
+
+  class << self
+    class ChompedIO # :nodoc:
+      def initialize(io)
+        @io = io
+      end
+      def gets
+        s = @io.gets
+        s.chomp if s
+      end
+    end
+
+    ##
+    # Creates a Dataset object from an Entry object. Used mostly to assist
+    # with the conversion of
+    def from_entry(entry)
+      dataset = Net::LDAP::Dataset.new
+      hash = { }
+      entry.each_attribute do |attribute, value|
+        next if attribute == :dn
+        hash[attribute] = value
+      end
+      dataset[entry.dn] = hash
+      dataset
+    end
+
+    ##
+    # Reads an object that returns data line-wise (using #gets) and parses
+    # LDIF data into a Dataset object.
+    def read_ldif(io)
+      ds = Net::LDAP::Dataset.new
+      io = ChompedIO.new(io)
+
+      line = io.gets
+      dn = nil
+
+      while line
+        new_line = io.gets
+
+        if new_line =~ /^ /
+          line << $'
+        else
+          nextline = new_line
+
+          if line =~ /^#/
+            ds.comments << line
+            yield :comment, line if block_given?
+          elsif line =~ /^dn:[\s]*/i
+            dn = $'
+            ds[dn] = Hash.new { |k,v| k[v] = [] }
+            yield :dn, dn if block_given?
+          elsif line.empty?
+            dn = nil
+            yield :end, nil if block_given?
+          elsif line =~ /^([^:]+):([\:]?)[\s]*/
+            # $1 is the attribute name
+            # $2 is a colon iff the attr-value is base-64 encoded
+            # $' is the attr-value
+            # Avoid the Base64 class because not all Ruby versions have it.
+            attrvalue = ($2 == ":") ? $'.unpack('m').shift : $'
+            ds[dn][$1.downcase.to_sym] << attrvalue
+            yield :attr, [$1.downcase.to_sym, attrvalue] if block_given?
+          end
+
+          line = nextline
+        end
+      end
+
+      ds
+    end
+  end
+end
+
+require 'net/ldap/entry' unless defined? Net::LDAP::Entry

data/lib/net/ldap/dn.rb

@@ -0,0 +1,225 @@
+# -*- ruby encoding: utf-8 -*-
+
+##
+# Objects of this class represent an LDAP DN ("Distinguished Name"). A DN
+# ("Distinguished Name") is a unique identifier for an entry within an LDAP
+# directory. It is made up of a number of other attributes strung together,
+# to identify the entry in the tree.
+#
+# Each attribute that makes up a DN needs to have its value escaped so that
+# the DN is valid. This class helps take care of that.
+#
+# A fully escaped DN needs to be unescaped when analysing its contents. This
+# class also helps take care of that.
+class Net::LDAP::DN
+  ##
+  # Initialize a DN, escaping as required. Pass in attributes in name/value
+  # pairs. If there is a left over argument, it will be appended to the dn
+  # without escaping (useful for a base string).
+  #
+  # Most uses of this class will be to escape a DN, rather than to parse it,
+  # so storing the dn as an escaped String and parsing parts as required
+  # with a state machine seems sensible.
+  def initialize(*args)
+    buffer = StringIO.new
+
+    args.each_index do |index|
+      buffer << "=" if index % 2 == 1
+      buffer << "," if index % 2 == 0 && index != 0
+
+      if index < args.length - 1 || index % 2 == 1
+        buffer << Net::LDAP::DN.escape(args[index])
+      else
+        buffer << args[index]
+      end
+    end
+
+    @dn = buffer.string
+  end
+
+  ##
+  # Parse a DN into key value pairs using ASN from
+  # http://tools.ietf.org/html/rfc2253 section 3.
+  def each_pair
+    state = :key
+    key = StringIO.new
+    value = StringIO.new
+    hex_buffer = ""
+
+    @dn.each_char do |char|
+      case state
+      when :key then
+        case char
+        when 'a'..'z', 'A'..'Z' then
+          state = :key_normal
+          key << char
+        when '0'..'9' then
+          state = :key_oid
+          key << char
+        when ' ' then state = :key
+        else raise "DN badly formed"
+        end
+      when :key_normal then
+        case char
+        when '=' then state = :value
+        when 'a'..'z', 'A'..'Z', '0'..'9', '-', ' ' then key << char
+        else raise "DN badly formed"
+        end
+      when :key_oid then
+        case char
+        when '=' then state = :value
+        when '0'..'9', '.', ' ' then key << char
+        else raise "DN badly formed"
+        end
+      when :value then
+        case char
+        when '\\' then state = :value_normal_escape
+        when '"' then state = :value_quoted
+        when ' ' then state = :value
+        when '#' then
+          state = :value_hexstring
+          value << char
+        when ',' then
+          state = :key
+          yield key.string.strip, value.string.rstrip
+          key = StringIO.new
+          value = StringIO.new;
+        else
+          state = :value_normal
+          value << char
+        end
+      when :value_normal then
+        case char
+        when '\\' then state = :value_normal_escape
+        when ',' then
+          state = :key
+          yield key.string.strip, value.string.rstrip
+          key = StringIO.new
+          value = StringIO.new;
+        else value << char
+        end
+      when :value_normal_escape then
+        case char
+        when '0'..'9', 'a'..'f', 'A'..'F' then
+          state = :value_normal_escape_hex
+          hex_buffer = char
+        else state = :value_normal; value << char
+        end
+      when :value_normal_escape_hex then
+        case char
+        when '0'..'9', 'a'..'f', 'A'..'F' then
+          state = :value_normal
+          value << "#{hex_buffer}#{char}".to_i(16).chr
+        else raise "DN badly formed"
+        end
+      when :value_quoted then
+        case char
+        when '\\' then state = :value_quoted_escape
+        when '"' then state = :value_end
+        else value << char
+        end
+      when :value_quoted_escape then
+        case char
+        when '0'..'9', 'a'..'f', 'A'..'F' then
+          state = :value_quoted_escape_hex
+          hex_buffer = char
+        else
+          state = :value_quoted;
+          value << char
+        end
+      when :value_quoted_escape_hex then
+        case char
+        when '0'..'9', 'a'..'f', 'A'..'F' then
+          state = :value_quoted
+          value << "#{hex_buffer}#{char}".to_i(16).chr
+        else raise "DN badly formed"
+        end
+      when :value_hexstring then
+        case char
+        when '0'..'9', 'a'..'f', 'A'..'F' then
+          state = :value_hexstring_hex
+          value << char
+        when ' ' then state = :value_end
+        when ',' then
+          state = :key
+          yield key.string.strip, value.string.rstrip
+          key = StringIO.new
+          value = StringIO.new;
+        else raise "DN badly formed"
+        end
+      when :value_hexstring_hex then
+        case char
+        when '0'..'9', 'a'..'f', 'A'..'F' then
+          state = :value_hexstring
+          value << char
+        else raise "DN badly formed"
+        end
+      when :value_end then
+        case char
+        when ' ' then state = :value_end
+        when ',' then
+          state = :key
+          yield key.string.strip, value.string.rstrip
+          key = StringIO.new
+          value = StringIO.new;
+        else raise "DN badly formed"
+        end
+      else raise "Fell out of state machine"
+      end
+    end
+
+    # Last pair
+    if [:value, :value_normal, :value_hexstring, :value_end].include? state
+      yield key.string.strip, value.string.rstrip
+    else
+      raise "DN badly formed"
+    end
+  end
+
+  ##
+  # Returns the DN as an array in the form expected by the constructor.
+  def to_a
+    a = []
+    self.each_pair { |key, value| a << key << value }
+    a
+  end
+
+  ##
+  # Return the DN as an escaped string.
+  def to_s
+    @dn
+  end
+
+  # http://tools.ietf.org/html/rfc2253 section 2.4 lists these exceptions
+  # for dn values. All of the following must be escaped in any normal string
+  # using a single backslash ('\') as escape.
+  ESCAPES = {
+    ','  => ',',
+    '+'  => '+',
+    '"'  => '"',
+    '\\' => '\\',
+    '<' => '<',
+    '>' => '>',
+    ';' => ';',
+  }
+
+  # Compiled character class regexp using the keys from the above hash, and
+  # checking for a space or # at the start, or space at the end, of the
+  # string.
+  ESCAPE_RE = Regexp.new("(^ |^#| $|[" +
+                         ESCAPES.keys.map { |e| Regexp.escape(e) }.join +
+                         "])")
+
+  ##
+  # Escape a string for use in a DN value
+  def self.escape(string)
+    string.gsub(ESCAPE_RE) { |char| "\\" + ESCAPES[char] }
+  end
+
+  ##
+  # Proxy all other requests to the string object, because a DN is mainly
+  # used within the library as a string
+  def method_missing(method, *args, &block)
+    @dn.send(method, *args, &block)
+  end
+end

data/lib/net/ldap/entry.rb

@@ -0,0 +1,185 @@
+# -*- ruby encoding: utf-8 -*-
+##
+# Objects of this class represent individual entries in an LDAP directory.
+# User code generally does not instantiate this class. Net::LDAP#search
+# provides objects of this class to user code, either as block parameters or
+# as return values.
+#
+# In LDAP-land, an "entry" is a collection of attributes that are uniquely
+# and globally identified by a DN ("Distinguished Name"). Attributes are
+# identified by short, descriptive words or phrases. Although a directory is
+# free to implement any attribute name, most of them follow rigorous
+# standards so that the range of commonly-encountered attribute names is not
+# large.
+#
+# An attribute name is case-insensitive. Most directories also restrict the
+# range of characters allowed in attribute names. To simplify handling
+# attribute names, Net::LDAP::Entry internally converts them to a standard
+# format. Therefore, the methods which take attribute names can take Strings
+# or Symbols, and work correctly regardless of case or capitalization.
+#
+# An attribute consists of zero or more data items called <i>values.</i> An
+# entry is the combination of a unique DN, a set of attribute names, and a
+# (possibly-empty) array of values for each attribute.
+#
+# Class Net::LDAP::Entry provides convenience methods for dealing with LDAP
+# entries. In addition to the methods documented below, you may access
+# individual attributes of an entry simply by giving the attribute name as
+# the name of a method call. For example:
+#
+#   ldap.search( ... ) do |entry|
+#     puts "Common name: #{entry.cn}"
+#     puts "Email addresses:"
+#     entry.mail.each {|ma| puts ma}
+#   end
+#
+# If you use this technique to access an attribute that is not present in a
+# particular Entry object, a NoMethodError exception will be raised.
+#
+#--
+# Ugly problem to fix someday: We key off the internal hash with a canonical
+# form of the attribute name: convert to a string, downcase, then take the
+# symbol. Unfortunately we do this in at least three places. Should do it in
+# ONE place.
+class Net::LDAP::Entry
+  ##
+  # This constructor is not generally called by user code.
+  def initialize(dn = nil) #:nodoc:
+    @myhash = {}
+    @myhash[:dn] = [dn]
+  end
+
+  ##
+  # Use the LDIF format for Marshal serialization.
+  def _dump(depth) #:nodoc:
+    to_ldif
+  end
+
+  ##
+  # Use the LDIF format for Marshal serialization.
+  def self._load(entry) #:nodoc:
+    from_single_ldif_string(entry)
+  end
+
+  class << self
+    ##
+    # Converts a single LDIF entry string into an Entry object. Useful for
+    # Marshal serialization. If a string with multiple LDIF entries is
+    # provided, an exception will be raised.
+    def from_single_ldif_string(ldif)
+      ds = Net::LDAP::Dataset.read_ldif(::StringIO.new(ldif))
+
+      return nil if ds.empty?
+
+      raise Net::LDAP::LdapError, "Too many LDIF entries" unless ds.size == 1
+
+      entry = ds.to_entries.first
+
+      return nil if entry.dn.nil?
+      entry
+    end
+
+    ##
+    # Canonicalizes an LDAP attribute name as a \Symbol. The name is
+    # lowercased and, if present, a trailing equals sign is removed.
+    def attribute_name(name)
+      name = name.to_s.downcase
+      name = name[0..-2] if name[-1] == ?=
+      name.to_sym
+    end
+  end
+
+  ##
+  # Sets or replaces the array of values for the provided attribute. The
+  # attribute name is canonicalized prior to assignment.
+  #
+  # When an attribute is set using this, that attribute is now made
+  # accessible through methods as well.
+  #
+  #   entry = Net::LDAP::Entry.new("dc=com")
+  #   entry.foo             # => NoMethodError
+  #   entry["foo"] = 12345  # => [12345]
+  #   entry.foo             # => [12345]
+  def []=(name, value)
+    @myhash[self.class.attribute_name(name)] = Kernel::Array(value)
+  end
+
+  ##
+  # Reads the array of values for the provided attribute. The attribute name
+  # is canonicalized prior to reading. Returns an empty array if the
+  # attribute does not exist.
+  def [](name)
+    name = self.class.attribute_name(name)
+    @myhash[name] || []
+  end
+
+  ##
+  # Returns the first distinguished name (dn) of the Entry as a \String.
+  def dn
+    self[:dn].first.to_s
+  end
+
+  ##
+  # Returns an array of the attribute names present in the Entry.
+  def attribute_names
+    @myhash.keys
+  end
+
+  ##
+  # Accesses each of the attributes present in the Entry.
+  #
+  # Calls a user-supplied block with each attribute in turn, passing two
+  # arguments to the block: a Symbol giving the name of the attribute, and a
+  # (possibly empty) \Array of data values.
+  def each # :yields: attribute-name, data-values-array
+    if block_given?
+      attribute_names.each {|a|
+        attr_name,values = a,self[a]
+        yield attr_name, values
+      }
+    end
+  end
+  alias_method :each_attribute, :each
+
+  ##
+  # Converts the Entry to an LDIF-formatted String
+  def to_ldif
+    Net::LDAP::Dataset.from_entry(self).to_ldif_string
+  end
+
+  def respond_to?(sym) #:nodoc:
+    return true if valid_attribute?(self.class.attribute_name(sym))
+    return super
+  end
+
+  def method_missing(sym, *args, &block) #:nodoc:
+    name = self.class.attribute_name(sym)
+
+    if valid_attribute?(name )
+      if setter?(sym) && args.size == 1
+        value = args.first
+        value = Array(value)
+        self[name]= value
+        return value
+      elsif args.empty?
+        return self[name]
+      end
+    end
+
+    super
+  end
+
+  # Given a valid attribute symbol, returns true.
+  def valid_attribute?(attr_name)
+    attribute_names.include?(attr_name)
+  end
+  private :valid_attribute?
+
+  # Returns true if the symbol ends with an equal sign.
+  def setter?(sym)
+    sym.to_s[-1] == ?=
+  end
+  private :setter?
+end # class Entry
+
+require 'net/ldap/dataset' unless defined? Net::LDAP::Dataset