diff --git a/lib/net/ldap.rb b/lib/net/ldap.rb index 0ec7fbb7..d76c4767 100644 --- a/lib/net/ldap.rb +++ b/lib/net/ldap.rb @@ -461,11 +461,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 all 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. The :simple_tls option is the simplest, easiest + # way to encrypt communications between Net::LDAP and LDAP servers. + # 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 simple TLS 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 +523,7 @@ 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 if pr = @auth[:password] and pr.respond_to?(:call) @auth[:password] = pr.call @@ -546,52 +587,16 @@ def authenticate(username, password) # additional capabilities are added, more configuration values will be # added here. # - # The :simple_tls encryption method encrypts all 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. The :simple_tls option is the simplest, easiest - # way to encrypt communications between Net::LDAP and LDAP servers. - # 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 simple TLS 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 diff --git a/test/test_ldap.rb b/test/test_ldap.rb index f30416b2..0c241f69 100644 --- a/test/test_ldap.rb +++ b/test/test_ldap.rb @@ -64,4 +64,10 @@ def test_obscure_auth @subject.auth "joe_user", password assert_not_include(@subject.inspect, password) end + + def test_encryption + enc = @subject.encryption('start_tls') + + assert_equal enc[:method], :start_tls + end end