Merge remote-tracking branch 'origin/master' into lazy-socket-initialization

Author: jch

.travis.yml

@@ -1,6 +1,5 @@
 language: ruby
 rvm:
-  - 1.9.3
   - 2.0.0
   - 2.1
   - 2.2
@@ -13,6 +12,9 @@ rvm:
 env:
   - INTEGRATION=openldap
 
+before_install:
+  - gem update bundler
+
 install:
   - if [ "$INTEGRATION" = "openldap" ]; then sudo script/install-openldap; fi
   - bundle install

Contributors.rdoc

@@ -22,3 +22,4 @@ Contributions since:
 * David J. Lee (DavidJLee)
 * Cody Cutrer (ccutrer)
 * WoodsBagotAndreMarquesLee
+* Rufus Post (mynameisrufus)

History.rdoc

@@ -1,3 +1,18 @@
+=== Net::LDAP 0.13.0
+
+* Set a connect_timeout for the creation of a socket {#243}[https://github.com/ruby-ldap/ruby-net-ldap/pull/243]
+* Update bundler before installing gems with bundler {#245}[https://github.com/ruby-ldap/ruby-net-ldap/pull/245]
+* Net::LDAP#encryption accepts string {#239}[https://github.com/ruby-ldap/ruby-net-ldap/pull/239]
+* Adds correct UTF-8 encoding to Net::BER::BerIdentifiedString {#242}[https://github.com/ruby-ldap/ruby-net-ldap/pull/242]
+* Remove 2.3.0-preview since ruby-head already is included {#241}[https://github.com/ruby-ldap/ruby-net-ldap/pull/241]
+* Drop support for ruby 1.9.3 {#240}[https://github.com/ruby-ldap/ruby-net-ldap/pull/240]
+* Fixed capitalization of StartTLSError {#234}[https://github.com/ruby-ldap/ruby-net-ldap/pull/234]
+
+=== Net::LDAP 0.12.1
+
+* Whitespace formatting cleanup {#236}[https://github.com/ruby-ldap/ruby-net-ldap/pull/236]
+* Set operation result if LDAP server is not accessible {#232}[https://github.com/ruby-ldap/ruby-net-ldap/pull/232]
+
 === Net::LDAP 0.12.0
 
 * DRY up connection handling logic {#224}[https://github.com/ruby-ldap/ruby-net-ldap/pull/224]

lib/net/ber.rb

@@ -106,6 +106,7 @@ module Net # :nodoc:
   # <tr><th>CHARACTER STRING</th><th>C</th><td>29: 61 (0x3d, 0b00111101)</td></tr>
   # <tr><th>BMPString</th><th>P</th><td>30: 30 (0x1e, 0b00011110)</td></tr>
   # <tr><th>BMPString</th><th>C</th><td>30: 62 (0x3e, 0b00111110)</td></tr>
+  # <tr><th>ExtendedResponse</th><th>C</th><td>107: 139 (0x8b, 0b010001011)</td></tr>
   # </table>
   module BER
     VERSION = Net::LDAP::VERSION
@@ -293,13 +294,43 @@ def to_arr
 
 ##
 # A String object with a BER identifier attached.
+#
 class Net::BER::BerIdentifiedString < String
   attr_accessor :ber_identifier
+
+  # The binary data provided when parsing the result of the LDAP search
+  # has the encoding 'ASCII-8BIT' (which is basically 'BINARY', or 'unknown').
+  #
+  # This is the kind of a backtrace showing how the binary `data` comes to
+  # BerIdentifiedString.new(data):
+  #
+  #  @conn.read_ber(syntax)
+  #     -> StringIO.new(self).read_ber(syntax), i.e. included from module
+  #     -> Net::BER::BERParser.read_ber(syntax)
+  #        -> (private)Net::BER::BERParser.parse_ber_object(syntax, id, data)
+  #
+  # In the `#parse_ber_object` method `data`, according to its OID, is being
+  # 'casted' to one of the Net::BER:BerIdentifiedXXX classes.
+  #
+  # As we are using LDAP v3 we can safely assume that the data is encoded
+  # in UTF-8 and therefore the only thing to be done when instantiating is to
+  # switch the encoding from 'ASCII-8BIT' to 'UTF-8'.
+  #
+  # Unfortunately, there are some ActiveDirectory specific attributes
+  # (like `objectguid`) that should remain binary (do they really?).
+  # Using the `#valid_encoding?` we can trap this cases. Special cases like
+  # Japanese, Korean, etc. encodings might also profit from this. However
+  # I have no clue how this encodings function.
   def initialize args
-    super begin
-      args.respond_to?(:encode) ? args.encode('UTF-8') : args
-    rescue
-      args
+    super
+    #
+    # Check the encoding of the newly created String and set the encoding
+    # to 'UTF-8' (NOTE: we do NOT change the bytes, but only set the
+    # encoding to 'UTF-8').
+    current_encoding = encoding
+    if current_encoding == Encoding::BINARY
+      force_encoding('UTF-8')
+      force_encoding(current_encoding) unless valid_encoding?
     end
   end
 end

lib/net/ldap.rb

@@ -79,6 +79,14 @@ class LDAP
 #
 #  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
 #
@@ -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
@@ -461,11 +477,52 @@ def self.result2string(code) #:nodoc:
   #   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.
+  #   with the LDAP server. The value must be a Hash containing additional
+  #   parameters, which consists of two keys:
+  #     method: - :simple_tls or :start_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>
+  #   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:
+  #
+  #     {
+  #       :method => :start_tls,
+  #       :tls_options => { :ca_file => "/etc/cafile.pem", :ssl_version => "TLSv1_1" }
+  #     }
   # * :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
@@ -482,7 +539,8 @@ def initialize(args = {})
     @auth = args[:auth] || DefaultAuth
     @base = args[:base] || DefaultTreebase
     @force_no_page = args[:force_no_page] || DefaultForceNoPage
-    encryption args[:encryption] # may be nil
+    @encryption = args[:encryption] # may be nil
+    @connect_timeout = args[:connect_timeout]
 
     if pr = @auth[:password] and pr.respond_to?(:call)
       @auth[:password] = pr.call
@@ -546,52 +604,16 @@ def authenticate(username, password)
   # 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:
-  #
-  #   {
-  #     :method => :start_tls,
-  #     :tls_options => { :ca_file => "/etc/cafile.pem", :ssl_version => "TLSv1_1" }
-  #   }
+  # This method is deprecated.
+  #
   def encryption(args)
-    case args
+    warn "Deprecation warning: please give :encryption option as a Hash to Net::LDAP.new"
+    return if args.nil?
+    return @encryption = args if args.is_a? Hash
+
+    case method = args.to_sym
     when :simple_tls, :start_tls
-      args = { :method => args, :tls_options => {} }
+      args = { :method => method, :tls_options => {} }
     end
     @encryption = args
   end
@@ -637,8 +659,11 @@ def self.open(args)
   #++
   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.
@@ -1027,6 +1052,44 @@ def modify(args)
     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
@@ -1247,12 +1310,13 @@ def new_connection
       :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, Net::LDAP::ConnectionRefusedError => e
+  rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, Net::LDAP::ConnectionRefusedError => e
     @result = {
       :resultCode   => 52,
       :errorMessage => ResultStrings[ResultCodeUnavailable]

lib/net/ldap/auth_adapter/gss_spnego.rb

@@ -29,10 +29,11 @@ def bind(auth)
             t3_msg.serialize
           }
 
-          Net::LDAP::AuthAdapter::Sasl.new(@connection).
-            bind(:method => :sasl, :mechanism => "GSS-SPNEGO",
-                    :initial_credential => NTLM::Message::Type1.new.serialize,
-                    :challenge_response => nego)
+          Net::LDAP::AuthAdapter::Sasl.new(@connection).bind \
+            :method             => :sasl,
+            :mechanism          => "GSS-SPNEGO",
+            :initial_credential => NTLM::Message::Type1.new.serialize,
+            :challenge_response => nego
         end
       end
     end