lib/net/ldap.rb in net-ldap-0.12.1 vs lib/net/ldap.rb in net-ldap-0.13.0
- old
+ new
@@ -77,11 +77,19 @@
# end
# end
#
# 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
#
# We're going to provide a quick, informal introduction to LDAP terminology
# and typical operations. If you're comfortable with this material, skip
# ahead to "How to use Net::LDAP." If you want a more rigorous treatment of
@@ -459,15 +467,56 @@
# then it will be used in subsequent calls to #search that do not
# 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.
+ # 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
# operations, compatible with ActiveSupport::Notifications' public API.
#
@@ -480,11 +529,12 @@
@hosts = args[:hosts]
@verbose = false # Make this configurable with a switch on the class.
@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
end
@@ -544,56 +594,20 @@
# (but see below for convenience alternatives). This implementation is
# currently a stub, supporting only a few encryption alternatives. As
# 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.
+ # This method is deprecated.
#
- # 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" }
- # }
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
# #open takes the same parameters as #new. #open makes a network
@@ -1240,11 +1254,12 @@
Net::LDAP::Connection.new \
:host => @host,
:port => @port,
:hosts => @hosts,
:encryption => @encryption,
- :instrumentation_service => @instrumentation_service
- rescue Errno::ECONNREFUSED, Net::LDAP::ConnectionRefusedError => e
+ :instrumentation_service => @instrumentation_service,
+ :connect_timeout => @connect_timeout
+ rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, Net::LDAP::ConnectionRefusedError => e
@result = {
:resultCode => 52,
:errorMessage => ResultStrings[ResultCodeUnavailable]
}
raise e