net-ldap 0.12.0 → 0.17.0

data/lib/net/ldap/password.rb

@@ -1,5 +1,6 @@
 # -*- ruby encoding: utf-8 -*-
 require 'digest/sha1'
+require 'digest/sha2'
 require 'digest/md5'
 require 'base64'
 require 'securerandom'
@@ -19,20 +20,21 @@ class Net::LDAP::Password
     # * Should we provide sha1 as a synonym for sha1? I vote no because then
     #   should you also provide ssha1 for symmetry?
     #
-    attribute_value = ""
     def generate(type, str)
       case type
       when :md5
-         attribute_value = '{MD5}' + Base64.encode64(Digest::MD5.digest(str)).chomp!
+         '{MD5}' + Base64.strict_encode64(Digest::MD5.digest(str))
       when :sha
-         attribute_value = '{SHA}' + Base64.encode64(Digest::SHA1.digest(str)).chomp!
+         '{SHA}' + Base64.strict_encode64(Digest::SHA1.digest(str))
       when :ssha
          salt = SecureRandom.random_bytes(16)
-         attribute_value = '{SSHA}' + Base64.encode64(Digest::SHA1.digest(str + salt) + salt).chomp!
+         '{SSHA}' + Base64.strict_encode64(Digest::SHA1.digest(str + salt) + salt)
+      when :ssha256
+        salt = SecureRandom.random_bytes(16)
+        '{SSHA256}' + Base64.strict_encode64(Digest::SHA256.digest(str + salt) + salt)
       else
          raise Net::LDAP::HashTypeUnsupportedError, "Unsupported password-hash type (#{type})"
       end
-      return attribute_value
     end
   end
 end

data/lib/net/ldap/pdu.rb

@@ -74,6 +74,7 @@ class Net::LDAP::PDU
   attr_reader :search_referrals
   attr_reader :search_parameters
   attr_reader :bind_parameters
+  attr_reader :extended_response
 
   ##
   # Returns RFC-2251 Controls if any.
@@ -120,9 +121,9 @@ class Net::LDAP::PDU
     when UnbindRequest
       parse_unbind_request(ber_object[1])
     when ExtendedResponse
-      parse_ldap_result(ber_object[1])
+      parse_extended_response(ber_object[1])
     else
-      raise LdapPduError.new("unknown pdu-type: #{@app_tag}")
+      raise Error.new("unknown pdu-type: #{@app_tag}")
     end
 
     parse_controls(ber_object[2]) if ber_object[2]
@@ -174,12 +175,35 @@ class Net::LDAP::PDU
     @ldap_result = {
       :resultCode => sequence[0],
       :matchedDN => sequence[1],
-      :errorMessage => sequence[2]
+      :errorMessage => sequence[2],
     }
     parse_search_referral(sequence[3]) if @ldap_result[:resultCode] == Net::LDAP::ResultCodeReferral
   end
   private :parse_ldap_result
 
+  ##
+  # Parse an extended response
+  #
+  # http://www.ietf.org/rfc/rfc2251.txt
+  #
+  # Each Extended operation consists of an Extended request and an
+  # Extended response.
+  #
+  #      ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
+  #           requestName      [0] LDAPOID,
+  #           requestValue     [1] OCTET STRING OPTIONAL }
+
+  def parse_extended_response(sequence)
+    sequence.length >= 3 or raise Net::LDAP::PDU::Error, "Invalid LDAP result length."
+    @ldap_result = {
+      :resultCode => sequence[0],
+      :matchedDN => sequence[1],
+      :errorMessage => sequence[2],
+    }
+    @extended_response = sequence[3]
+  end
+  private :parse_extended_response
+
   ##
   # A Bind Response may have an additional field, ID [7], serverSaslCreds,
   # per RFC 2251 pgh 4.2.3.

data/lib/net/ldap/version.rb

@@ -1,5 +1,5 @@
 module Net
   class LDAP
-    VERSION = "0.12.0"
+    VERSION = "0.17.0"
   end
 end

data/lib/net/ldap.rb

@@ -17,19 +17,19 @@ module Net # :nodoc:
 end
 require 'socket'
 
-require 'net/ber'
-require 'net/ldap/pdu'
-require 'net/ldap/filter'
-require 'net/ldap/dataset'
-require 'net/ldap/password'
-require 'net/ldap/entry'
-require 'net/ldap/instrumentation'
-require 'net/ldap/connection'
-require 'net/ldap/version'
-require 'net/ldap/error'
-require 'net/ldap/auth_adapter'
-require 'net/ldap/auth_adapter/simple'
-require 'net/ldap/auth_adapter/sasl'
+require_relative 'ber'
+require_relative 'ldap/pdu'
+require_relative 'ldap/filter'
+require_relative 'ldap/dataset'
+require_relative 'ldap/password'
+require_relative 'ldap/entry'
+require_relative 'ldap/instrumentation'
+require_relative 'ldap/connection'
+require_relative 'ldap/version'
+require_relative 'ldap/error'
+require_relative 'ldap/auth_adapter'
+require_relative 'ldap/auth_adapter/simple'
+require_relative 'ldap/auth_adapter/sasl'
 
 Net::LDAP::AuthAdapter.register([:simple, :anon, :anonymous], Net::LDAP::AuthAdapter::Simple)
 Net::LDAP::AuthAdapter.register(:sasl, Net::LDAP::AuthAdapter::Sasl)
@@ -79,6 +79,14 @@ Net::LDAP::AuthAdapter.register(:sasl, Net::LDAP::AuthAdapter::Sasl)
 #
 #  p ldap.get_operation_result
 #
+# === Setting connect timeout
+#
+# By default, Net::LDAP uses TCP sockets with a connection timeout of 5 seconds.
+#
+# This value can be tweaked passing the :connect_timeout parameter.
+# i.e.
+#  ldap = Net::LDAP.new ...,
+#                       :connect_timeout => 3
 #
 # == A Brief Introduction to LDAP
 #
@@ -256,14 +264,14 @@ class Net::LDAP
   SearchScope_BaseObject = 0
   SearchScope_SingleLevel = 1
   SearchScope_WholeSubtree = 2
-  SearchScopes = [ SearchScope_BaseObject, SearchScope_SingleLevel,
-    SearchScope_WholeSubtree ]
+  SearchScopes = [SearchScope_BaseObject, SearchScope_SingleLevel,
+    SearchScope_WholeSubtree]
 
   DerefAliases_Never = 0
   DerefAliases_Search = 1
   DerefAliases_Find = 2
   DerefAliases_Always = 3
-  DerefAliasesArray = [ DerefAliases_Never, DerefAliases_Search, DerefAliases_Find, DerefAliases_Always ]
+  DerefAliasesArray = [DerefAliases_Never, DerefAliases_Search, DerefAliases_Find, DerefAliases_Always]
 
   primitive = { 2 => :null } # UnbindRequest body
   constructed = {
@@ -315,7 +323,14 @@ class Net::LDAP
     :constructed => constructed,
   }
 
+  universal = {
+    constructed: {
+      107 => :array, #ExtendedResponse (PasswdModifyResponseValue)
+    },
+  }
+
   AsnSyntax = Net::BER.compile_syntax(:application => application,
+                                      :universal => universal,
                                       :context_specific => context_specific)
 
   DefaultHost = "127.0.0.1"
@@ -324,7 +339,8 @@ class Net::LDAP
   DefaultTreebase = "dc=com"
   DefaultForceNoPage = false
 
-  StartTlsOid = "1.3.6.1.4.1.1466.20037"
+  StartTlsOid = '1.3.6.1.4.1.1466.20037'
+  PasswdModifyOid = '1.3.6.1.4.1.4203.1.11.1'
 
   # https://tools.ietf.org/html/rfc4511#section-4.1.9
   # https://tools.ietf.org/html/rfc4511#appendix-A
@@ -373,14 +389,14 @@ class Net::LDAP
     ResultCodeCompareFalse,
     ResultCodeCompareTrue,
     ResultCodeReferral,
-    ResultCodeSaslBindInProgress
+    ResultCodeSaslBindInProgress,
   ]
 
   # nonstandard list of "successful" result codes for searches
   ResultCodesSearchSuccess = [
     ResultCodeSuccess,
     ResultCodeTimeLimitExceeded,
-    ResultCodeSizeLimitExceeded
+    ResultCodeSizeLimitExceeded,
   ]
 
   # map of result code to human message
@@ -422,7 +438,7 @@ class Net::LDAP
     ResultCodeEntryAlreadyExists           => "Entry Already Exists",
     ResultCodeObjectClassModsProhibited    => "ObjectClass Modifications Prohibited",
     ResultCodeAffectsMultipleDSAs          => "Affects Multiple DSAs",
-    ResultCodeOther                        => "Other"
+    ResultCodeOther                        => "Other",
   }
 
   module LDAPControls
@@ -460,20 +476,73 @@ class Net::LDAP
   #   specify a treebase. If you give a treebase value in any particular
   #   call to #search, that value will override any treebase value you give
   #   here.
-  # * :encryption => specifies the encryption to be used in communicating
-  #   with the LDAP server. The value is either a Hash containing additional
-  #   parameters, or the Symbol :simple_tls, which is equivalent to
-  #   specifying the Hash {:method => :simple_tls}. There is a fairly large
-  #   range of potential values that may be given for this parameter. See
-  #   #encryption for details.
   # * :force_no_page => Set to true to prevent paged results even if your
   #   server says it supports them. This is a fix for MS Active Directory
   # * :instrumentation_service => An object responsible for instrumenting
   #   operations, compatible with ActiveSupport::Notifications' public API.
+  # * :encryption => specifies the encryption to be used in communicating
+  #   with the LDAP server. The value must be a Hash containing additional
+  #   parameters, which consists of two keys:
+  #     method: - :simple_tls or :start_tls
+  #     tls_options: - Hash of options for that method
+  #   The :simple_tls encryption method encrypts <i>all</i> communications
+  #   with the LDAP server. It completely establishes SSL/TLS encryption with
+  #   the LDAP server before any LDAP-protocol data is exchanged. There is no
+  #   plaintext negotiation and no special encryption-request controls are
+  #   sent to the server. <i>The :simple_tls option is the simplest, easiest
+  #   way to encrypt communications between Net::LDAP and LDAP servers.</i>
+  #   If you get communications or protocol errors when using this option,
+  #   check with your LDAP server administrator. Pay particular attention
+  #   to the TCP port you are connecting to. It's impossible for an LDAP
+  #   server to support plaintext LDAP communications and <i>simple TLS</i>
+  #   connections on the same port. The standard TCP port for unencrypted
+  #   LDAP connections is 389, but the standard port for simple-TLS
+  #   encrypted connections is 636. Be sure you are using the correct port.
+  #   The :start_tls like the :simple_tls encryption method also encrypts all
+  #   communcations with the LDAP server. With the exception that it operates
+  #   over the standard TCP port.
+  #
+  #   To validate the LDAP server's certificate (a security must if you're
+  #   talking over the public internet), you need to set :tls_options
+  #   something like this...
+  #
+  #   Net::LDAP.new(
+  #     # ... set host, bind dn, etc ...
+  #     encryption: {
+  #       method: :simple_tls,
+  #       tls_options: OpenSSL::SSL::SSLContext::DEFAULT_PARAMS,
+  #     }
+  #   )
+  #
+  #   The above will use the operating system-provided store of CA
+  #   certificates to validate your LDAP server's cert.
+  #   If cert validation fails, it'll happen during the #bind
+  #   whenever you first try to open a connection to the server.
+  #   Those methods will throw Net::LDAP::ConnectionError with
+  #   a message about certificate verify failing. If your
+  #   LDAP server's certificate is signed by DigiCert, Comodo, etc.,
+  #   you're probably good. If you've got a self-signed cert but it's
+  #   been added to the host's OS-maintained CA store (e.g. on Debian
+  #   add foobar.crt to /usr/local/share/ca-certificates/ and run
+  #   `update-ca-certificates`), then the cert should pass validation.
+  #   To ignore the OS's CA store, put your CA in a PEM-encoded file and...
+  #
+  #   encryption: {
+  #     method:      :simple_tls,
+  #     tls_options: { ca_file:     '/path/to/my-little-ca.pem',
+  #                    ssl_version: 'TLSv1_1' },
+  #   }
+  #
+  #   As you might guess, the above example also fails the connection
+  #   if the client can't negotiate TLS v1.1.
+  #   tls_options is ultimately passed to OpenSSL::SSL::SSLContext#set_params
+  #   For more details, see
+  #    http://ruby-doc.org/stdlib-2.0.0/libdoc/openssl/rdoc/OpenSSL/SSL/SSLContext.html
   #
   # Instantiating a Net::LDAP object does <i>not</i> result in network
   # traffic to the LDAP server. It simply stores the connection and binding
-  # parameters in the object.
+  # parameters in the object. That's why Net::LDAP.new doesn't throw
+  # cert validation errors itself; #bind does instead.
   def initialize(args = {})
     @host = args[:host] || DefaultHost
     @port = args[:port] || DefaultPort
@@ -482,7 +551,8 @@ class Net::LDAP
     @auth = args[:auth] || DefaultAuth
     @base = args[:base] || DefaultTreebase
     @force_no_page = args[:force_no_page] || DefaultForceNoPage
-    encryption args[:encryption] # may be nil
+    @encryption = normalize_encryption(args[:encryption]) # may be nil
+    @connect_timeout = args[:connect_timeout]
 
     if pr = @auth[:password] and pr.respond_to?(:call)
       @auth[:password] = pr.call
@@ -533,7 +603,7 @@ class Net::LDAP
     @auth = {
       :method => :simple,
       :username => username,
-      :password => password
+      :password => password,
     }
   end
   alias_method :auth, :authenticate
@@ -546,54 +616,12 @@ class Net::LDAP
   # additional capabilities are added, more configuration values will be
   # added here.
   #
-  # The :simple_tls encryption method encrypts <i>all</i> communications
-  # with the LDAP server. It completely establishes SSL/TLS encryption with
-  # the LDAP server before any LDAP-protocol data is exchanged. There is no
-  # plaintext negotiation and no special encryption-request controls are
-  # sent to the server. <i>The :simple_tls option is the simplest, easiest
-  # way to encrypt communications between Net::LDAP and LDAP servers.</i>
-  # It's intended for cases where you have an implicit level of trust in the
-  # authenticity of the LDAP server. No validation of the LDAP server's SSL
-  # certificate is performed. This means that :simple_tls will not produce
-  # errors if the LDAP server's encryption certificate is not signed by a
-  # well-known Certification Authority. If you get communications or
-  # protocol errors when using this option, check with your LDAP server
-  # administrator. Pay particular attention to the TCP port you are
-  # connecting to. It's impossible for an LDAP server to support plaintext
-  # LDAP communications and <i>simple TLS</i> connections on the same port.
-  # The standard TCP port for unencrypted LDAP connections is 389, but the
-  # standard port for simple-TLS encrypted connections is 636. Be sure you
-  # are using the correct port.
-  #
-  # The :start_tls like the :simple_tls encryption method also encrypts all
-  # communcations with the LDAP server. With the exception that it operates
-  # over the standard TCP port.
-  #
-  # In order to verify certificates and enable other TLS options, the
-  # :tls_options hash can be passed alongside :simple_tls or :start_tls.
-  # This hash contains any options that can be passed to
-  # OpenSSL::SSL::SSLContext#set_params(). The most common options passed
-  # should be OpenSSL::SSL::SSLContext::DEFAULT_PARAMS, or the :ca_file option,
-  # which contains a path to a Certificate Authority file (PEM-encoded).
-  #
-  # Example for a default setup without custom settings:
-  #   {
-  #     :method => :simple_tls,
-  #     :tls_options => OpenSSL::SSL::SSLContext::DEFAULT_PARAMS
-  #   }
-  #
-  # Example for specifying a CA-File and only allowing TLSv1.1 connections:
+  # This method is deprecated.
   #
-  #   {
-  #     :method => :start_tls,
-  #     :tls_options => { :ca_file => "/etc/cafile.pem", :ssl_version => "TLSv1_1" }
-  #   }
   def encryption(args)
-    case args
-    when :simple_tls, :start_tls
-      args = { :method => args, :tls_options => {} }
-    end
-    @encryption = args
+    warn "Deprecation warning: please give :encryption option as a Hash to Net::LDAP.new"
+    return if args.nil?
+    @encryption = normalize_encryption(args)
   end
 
   # #open takes the same parameters as #new. #open makes a network
@@ -637,8 +665,11 @@ class Net::LDAP
   #++
   def get_operation_result
     result = @result
-    result = result.result if result.is_a?(Net::LDAP::PDU)
     os = OpenStruct.new
+    if result.is_a?(Net::LDAP::PDU)
+      os.extended_response = result.extended_response
+      result = result.result
+    end
     if result.is_a?(Hash)
       # We might get a hash of LDAP response codes instead of a simple
       # numeric code.
@@ -681,7 +712,7 @@ class Net::LDAP
       begin
         @open_connection = new_connection
         payload[:connection] = @open_connection
-        payload[:bind]       = @open_connection.bind(@auth)
+        payload[:bind]       = @result = @open_connection.bind(@auth)
         yield self
       ensure
         @open_connection.close if @open_connection
@@ -750,10 +781,10 @@ class Net::LDAP
 
     instrument "search.net_ldap", args do |payload|
       @result = use_connection(args) do |conn|
-        conn.search(args) { |entry|
+        conn.search(args) do |entry|
           result_set << entry if result_set
           yield entry if block_given?
-        }
+        end
       end
 
       if return_result_set
@@ -892,7 +923,7 @@ class Net::LDAP
   #  end
   def bind_as(args = {})
     result = false
-    open { |me|
+    open do |me|
       rs = search args
       if rs and rs.first and dn = rs.first.dn
         password = args[:password]
@@ -900,7 +931,7 @@ class Net::LDAP
         result = rs if bind(:method => :simple, :username => dn,
                             :password => password)
       end
-    }
+    end
     result
   end
 
@@ -1027,6 +1058,44 @@ class Net::LDAP
     end
   end
 
+  # Password Modify
+  #
+  # Change existing password:
+  #
+  #  dn = 'uid=modify-password-user1,ou=People,dc=rubyldap,dc=com'
+  #  auth = {
+  #    method: :simple,
+  #    username: dn,
+  #    password: 'passworD1'
+  #  }
+  #  ldap.password_modify(dn: dn,
+  #                       auth: auth,
+  #                       old_password: 'passworD1',
+  #                       new_password: 'passworD2')
+  #
+  # Or get the LDAP server to generate a password for you:
+  #
+  #  dn = 'uid=modify-password-user1,ou=People,dc=rubyldap,dc=com'
+  #  auth = {
+  #    method: :simple,
+  #    username: dn,
+  #    password: 'passworD1'
+  #  }
+  #  ldap.password_modify(dn: dn,
+  #                       auth: auth,
+  #                       old_password: 'passworD1')
+  #
+  #  ldap.get_operation_result.extended_response[0][0] #=> 'VtcgGf/G'
+  #
+  def password_modify(args)
+    instrument "modify_password.net_ldap", args do |payload|
+      @result = use_connection(args) do |conn|
+        conn.password_modify(args)
+      end
+      @result.success?
+    end
+  end
+
   # Add a value to an attribute. Takes the full DN of the entry to modify,
   # the name (Symbol or String) of the attribute, and the value (String or
   # Array). If the attribute does not exist (and there are no schema
@@ -1113,14 +1182,22 @@ class Net::LDAP
   # entries. This method sends an extra control code to tell the LDAP server
   # to do a tree delete. ('1.2.840.113556.1.4.805')
   #
+  # If the LDAP server does not support the DELETE_TREE control code, subordinate
+  # entries are deleted recursively instead.
+  #
   # Returns True or False to indicate whether the delete succeeded. Extended
   # status information is available by calling #get_operation_result.
   #
   #  dn = "mail=deleteme@example.com, ou=people, dc=example, dc=com"
   #  ldap.delete_tree :dn => dn
   def delete_tree(args)
-    delete(args.merge(:control_codes => [[Net::LDAP::LDAPControls::DELETE_TREE, true]]))
+    if search_root_dse[:supportedcontrol].include? Net::LDAP::LDAPControls::DELETE_TREE
+      delete(args.merge(:control_codes => [[Net::LDAP::LDAPControls::DELETE_TREE, true]]))
+    else
+      recursive_delete(args)
+    end
   end
+
   # This method is experimental and subject to change. Return the rootDSE
   # record from the LDAP server as a Net::LDAP::Entry, or an empty Entry if
   # the server doesn't return the record.
@@ -1145,7 +1222,7 @@ class Net::LDAP
                   :supportedExtension,
                   :supportedFeatures,
                   :supportedLdapVersion,
-                  :supportedSASLMechanisms
+                  :supportedSASLMechanisms,
                 ])
     (rs and rs.first) or Net::LDAP::Entry.new
   end
@@ -1212,6 +1289,11 @@ class Net::LDAP
     inspected
   end
 
+  # Internal: Set @open_connection for testing
+  def connection=(connection)
+    @open_connection = connection
+  end
+
   private
 
   # Yields an open connection if there is one, otherwise establishes a new
@@ -1224,11 +1306,9 @@ class Net::LDAP
     else
       begin
         conn = new_connection
-        if (result = conn.bind(args[:auth] || @auth)).result_code == Net::LDAP::ResultCodeSuccess
-          yield conn
-        else
-          return result
-        end
+        result = conn.bind(args[:auth] || @auth)
+        return result unless result.result_code == Net::LDAP::ResultCodeSuccess
+        yield conn
       ensure
         conn.close if conn
       end
@@ -1237,11 +1317,50 @@ class Net::LDAP
 
   # Establish a new connection to the LDAP server
   def new_connection
-    Net::LDAP::Connection.new \
+    connection = Net::LDAP::Connection.new \
       :host                    => @host,
       :port                    => @port,
       :hosts                   => @hosts,
       :encryption              => @encryption,
-      :instrumentation_service => @instrumentation_service
+      :instrumentation_service => @instrumentation_service,
+      :connect_timeout         => @connect_timeout
+
+    # Force connect to see if there's a connection error
+    connection.socket
+    connection
+  rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT => e
+    @result = {
+      :resultCode   => 52,
+      :errorMessage => ResultStrings[ResultCodeUnavailable],
+    }
+    raise e
+  end
+
+  # Normalize encryption parameter the constructor accepts, expands a few
+  # convenience symbols into recognizable hashes
+  def normalize_encryption(args)
+    return if args.nil?
+    return args if args.is_a? Hash
+
+    case method = args.to_sym
+    when :simple_tls, :start_tls
+      { :method => method, :tls_options => {} }
+    end
+  end
+
+  # Recursively delete a dn and it's subordinate children.
+  # This is useful when a server does not support the DELETE_TREE control code.
+  def recursive_delete(args)
+    raise EmptyDNError unless args.is_a?(Hash) && args.key?(:dn)
+    # Delete Children
+    search(base: args[:dn], scope: Net::LDAP::SearchScope_SingleLevel) do |entry|
+      recursive_delete(dn: entry.dn)
+    end
+    # Delete Self
+    unless delete(dn: args[:dn])
+      raise Net::LDAP::Error, get_operation_result[:error_message].to_s
+    end
+    true
   end
+
 end # class LDAP