Implement custom tls options

This allows users of the API to either specify a simple CA-File for
certificate verification, or a custom SSLContext in order for a more
fine-grained control of the TLS options they want to use.

As of now, no additional tests were added, but the existing tests were
changed to reflect the changes in internal methods, so that they can
still pass

Author: sonOfRa

lib/net/ldap.rb

@@ -537,10 +537,6 @@ def authenticate(username, password)
   # additional capabilities are added, more configuration values will be
   # added here.
   #
-  # Currently, the only supported argument is { :method => :simple_tls }.
-  # (Equivalently, you may pass the symbol :simple_tls all by itself,
-  # without enclosing it in a Hash.)
-  #
   # 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
@@ -563,6 +559,17 @@ def authenticate(username, password)
   # 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 allow verification of server certificates and other TLS-related
+  # options, the keys :cafile and :ssl_context can be used.
+  #
+  # The :cafile option  is a single filename that points to one or more
+  # PEM-encoded certificates. These certificates are used as a certificate auhority
+  # to verify the server certificates.
+  #
+  # For fine-grained control of the TLS settings, it is also possible to use the
+  # :ssl_context option to pass a custom OpenSSL::SSL::SSLContext. Consult the
+  # OpenSSL documentation for more information on the available options.
   def encryption(args)
     case args
     when :simple_tls, :start_tls

lib/net/ldap/connection.rb

@@ -17,6 +17,8 @@ def initialize(server)
       raise Net::LDAP::LdapError, "Server #{server[:host]} refused connection on port #{server[:port]}."
     rescue Errno::EHOSTUNREACH => error
       raise Net::LDAP::LdapError, "Host #{server[:host]} was unreachable (#{error.message})"
+    rescue Errno::ETIMEDOUT
+      raise Net::LDAP::LdapError, "Connection to #{server[:host]} timed out."
     end
 
     if server[:encryption]
@@ -39,9 +41,20 @@ def close
     end
   end
 
-  def self.wrap_with_ssl(io)
+  def self.wrap_with_ssl(io, ssl_context = nil, cafile = nil)
     raise Net::LDAP::LdapError, "OpenSSL is unavailable" unless Net::LDAP::HasOpenSSL
-    ctx = OpenSSL::SSL::SSLContext.new
+    if (ssl_context && cafile)
+      raise Net::LDAP::LdapError, "Please specify only one of ssl_context or cafile"
+    end
+
+    ctx = ssl_context ? ssl_context : OpenSSL::SSL::SSLContext.new
+
+    # OpenSSL automatically merges the given parameters with the default parameters
+    # These include verification and some common workarounds
+    if cafile
+      ctx.set_params({:ca_file => cafile})
+    end
+
     conn = OpenSSL::SSL::SSLSocket.new(io, ctx)
     conn.connect
 
@@ -83,7 +96,7 @@ def self.wrap_with_ssl(io)
   def setup_encryption(args)
     case args[:method]
     when :simple_tls
-      @conn = self.class.wrap_with_ssl(@conn)
+      @conn = self.class.wrap_with_ssl(@conn, args[:ssl_context], args[:cafile])
       # additional branches requiring server validation and peer certs, etc.
       # go here.
     when :start_tls
@@ -100,7 +113,7 @@ def setup_encryption(args)
       end
 
       if pdu.result_code.zero?
-        @conn = self.class.wrap_with_ssl(@conn)
+        @conn = self.class.wrap_with_ssl(@conn, args[:ssl_context], args[:cafile])
       else
         raise Net::LDAP::LdapError, "start_tls failed: #{pdu.result_code}"
       end

test/test_ldap_connection.rb

@@ -202,7 +202,7 @@ def test_queued_read_setup_encryption_with_start_tls
       and_return(result2)
     mock.should_receive(:write)
     conn = Net::LDAP::Connection.new(:socket => mock)
-    flexmock(Net::LDAP::Connection).should_receive(:wrap_with_ssl).with(mock).
+    flexmock(Net::LDAP::Connection).should_receive(:wrap_with_ssl).with(mock, nil, nil).
       and_return(mock)
 
     conn.next_msgid # simulates ongoing query