net-ldap 0.3.1 → 0.17.0

data/lib/net/ber/core_ext.rb

@@ -1,5 +1,5 @@
 # -*- ruby encoding: utf-8 -*-
-require 'net/ber/ber_parser'
+require_relative 'ber_parser'
 # :stopdoc:
 class IO
   include Net::BER::BERParser
@@ -19,44 +19,37 @@ end
 module Net::BER::Extensions # :nodoc:
 end
 
-require 'net/ber/core_ext/string'
+require_relative 'core_ext/string'
 # :stopdoc:
 class String
   include Net::BER::BERParser
   include Net::BER::Extensions::String
 end
 
-require 'net/ber/core_ext/array'
+require_relative 'core_ext/array'
 # :stopdoc:
-class Array 
+class Array
   include Net::BER::Extensions::Array
 end
 # :startdoc:
 
-require 'net/ber/core_ext/bignum'
+require_relative 'core_ext/integer'
 # :stopdoc:
-class Bignum 
-  include Net::BER::Extensions::Bignum
+class Integer
+  include Net::BER::Extensions::Integer
 end
 # :startdoc:
 
-require 'net/ber/core_ext/fixnum'
+require_relative 'core_ext/true_class'
 # :stopdoc:
-class Fixnum 
-  include Net::BER::Extensions::Fixnum
-end
-# :startdoc:
-
-require 'net/ber/core_ext/true_class'
-# :stopdoc:
-class TrueClass 
+class TrueClass
   include Net::BER::Extensions::TrueClass
 end
 # :startdoc:
 
-require 'net/ber/core_ext/false_class'
+require_relative 'core_ext/false_class'
 # :stopdoc:
-class FalseClass 
+class FalseClass
   include Net::BER::Extensions::FalseClass
 end
 # :startdoc:

data/lib/net/ber/core_ext/array.rb

@@ -79,4 +79,18 @@ module Net::BER::Extensions::Array
     oid = ary.pack("w*")
     [6, oid.length].pack("CC") + oid
   end
+
+  ##
+  # Converts an array into a set of ber control codes
+  # The expected format is [[control_oid, criticality, control_value(optional)]]
+  #   [['1.2.840.113556.1.4.805',true]]
+  #
+  def to_ber_control
+    #if our array does not contain at least one array then wrap it in an array before going forward
+    ary = self[0].kind_of?(Array) ? self : [self]
+    ary = ary.collect do |control_sequence|
+      control_sequence.collect(&:to_ber).to_ber_sequence.reject_empty_ber_arrays
+    end
+    ary.to_ber_sequence.reject_empty_ber_arrays
+  end
 end

data/lib/net/ber/core_ext/integer.rb

@@ -0,0 +1,74 @@
+# -*- ruby encoding: utf-8 -*-
+##
+# BER extensions to the Integer class, affecting Fixnum and Bignum objects.
+module Net::BER::Extensions::Integer
+  ##
+  # Converts the Integer to BER format.
+  def to_ber
+    "\002#{to_ber_internal}"
+  end
+
+  ##
+  # Converts the Integer to BER enumerated format.
+  def to_ber_enumerated
+    "\012#{to_ber_internal}"
+  end
+
+  ##
+  # Converts the Integer to BER length encoding format.
+  def to_ber_length_encoding
+    if self <= 127
+      [self].pack('C')
+    else
+      i = [self].pack('N').sub(/^[\0]+/, "")
+      [0x80 + i.length].pack('C') + i
+    end
+  end
+
+  ##
+  # Generate a BER-encoding for an application-defined INTEGER. Examples of
+  # such integers are SNMP's Counter, Gauge, and TimeTick types.
+  def to_ber_application(tag)
+    [0x40 + tag].pack("C") + to_ber_internal
+  end
+
+  ##
+  # Used to BER-encode the length and content bytes of an Integer. Callers
+  # must prepend the tag byte for the contained value.
+  def to_ber_internal
+    # Compute the byte length, accounting for negative values requiring two's
+    # complement.
+    size  = 1
+    size += 1 until (((self < 0) ? ~self : self) >> (size * 8)).zero?
+
+    # Padding for positive, negative values. See section 8.5 of ITU-T X.690:
+    # http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf
+
+    # For positive integers, if most significant bit in an octet is set to one,
+    # pad the result (otherwise it's decoded as a negative value).
+    if self > 0 && (self & (0x80 << (size - 1) * 8)) > 0
+      size += 1
+    end
+
+    # And for negative integers, pad if the most significant bit in the octet
+    # is not set to one (othwerise, it's decoded as positive value).
+    if self < 0 && (self & (0x80 << (size - 1) * 8)) == 0
+      size += 1
+    end
+
+    # Store the size of the Integer in the result
+    result = [size]
+
+    # Appends bytes to result, starting with higher orders first. Extraction
+    # of bytes is done by right shifting the original Integer by an amount
+    # and then masking that with 0xff.
+    while size > 0
+      # right shift size - 1 bytes, mask with 0xff
+      result << ((self >> ((size - 1) * 8)) & 0xff)
+      size -= 1
+    end
+
+    result.pack('C*')
+  end
+  private :to_ber_internal
+end

data/lib/net/ber/core_ext/string.rb

@@ -16,11 +16,27 @@ module Net::BER::Extensions::String
     [code].pack('C') + raw_string.length.to_ber_length_encoding + raw_string
   end
 
+  ##
+  # Converts a string to a BER string but does *not* encode to UTF-8 first.
+  # This is required for proper representation of binary data for Microsoft
+  # Active Directory
+  def to_ber_bin(code = 0x04)
+    [code].pack('C') + length.to_ber_length_encoding + self
+  end
+
   def raw_utf8_encoded
     if self.respond_to?(:encode)
       # Strings should be UTF-8 encoded according to LDAP.
       # However, the BER code is not necessarily valid UTF-8
-      self.encode('UTF-8').force_encoding('ASCII-8BIT')
+      begin
+        self.encode('UTF-8').force_encoding('ASCII-8BIT')
+      rescue Encoding::UndefinedConversionError
+        self
+      rescue Encoding::ConverterNotFoundError
+        self
+      rescue Encoding::InvalidByteSequenceError
+        self
+      end
     else
       self
     end
@@ -46,15 +62,19 @@ module Net::BER::Extensions::String
   def read_ber(syntax = nil)
     StringIO.new(self).read_ber(syntax)
   end
-  
+
   ##
-  # Destructively reads a BER object from the string. 
+  # Destructively reads a BER object from the string.
   def read_ber!(syntax = nil)
     io = StringIO.new(self)
 
     result = io.read_ber(syntax)
     self.slice!(0...io.pos)
-    
+
     return result
   end
+
+  def reject_empty_ber_arrays
+    self.gsub(/0\000/n, '')
+  end
 end

data/lib/net/ber/core_ext/true_class.rb

@@ -5,8 +5,7 @@ module Net::BER::Extensions::TrueClass
   ##
   # Converts +true+ to the BER wireline representation of +true+.
   def to_ber
-    # 20100319 AZ: Note that this may not be the completely correct value,
-    # per some test documentation. We need to determine the truth of this.
-    "\001\001\001"
+    # http://tools.ietf.org/html/rfc4511#section-5.1
+    "\001\001\xFF".force_encoding("ASCII-8BIT")
   end
 end

data/lib/net/ldap.rb

@@ -17,12 +17,22 @@ 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_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)
 
 # == Quick-start for the Impatient
 # === Quick Example of a user-authentication against an LDAP directory:
@@ -69,6 +79,14 @@ require 'net/ldap/entry'
 #
 #  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
 #
@@ -241,15 +259,19 @@ require 'net/ldap/entry'
 # and then keeps it open while it executes a user-supplied block.
 # Net::LDAP#open closes the connection on completion of the block.
 class Net::LDAP
-  VERSION = "0.3.1"
-
-  class LdapError < StandardError; end
+  include Net::LDAP::Instrumentation
 
   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]
 
   primitive = { 2 => :null } # UnbindRequest body
   constructed = {
@@ -301,42 +323,129 @@ 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"
   DefaultPort = 389
   DefaultAuth = { :method => :anonymous }
   DefaultTreebase = "dc=com"
-
-  StartTlsOid = "1.3.6.1.4.1.1466.20037"
-
+  DefaultForceNoPage = false
+
+  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
+  ResultCodeSuccess                      = 0
+  ResultCodeOperationsError              = 1
+  ResultCodeProtocolError                = 2
+  ResultCodeTimeLimitExceeded            = 3
+  ResultCodeSizeLimitExceeded            = 4
+  ResultCodeCompareFalse                 = 5
+  ResultCodeCompareTrue                  = 6
+  ResultCodeAuthMethodNotSupported       = 7
+  ResultCodeStrongerAuthRequired         = 8
+  ResultCodeReferral                     = 10
+  ResultCodeAdminLimitExceeded           = 11
+  ResultCodeUnavailableCriticalExtension = 12
+  ResultCodeConfidentialityRequired      = 13
+  ResultCodeSaslBindInProgress           = 14
+  ResultCodeNoSuchAttribute              = 16
+  ResultCodeUndefinedAttributeType       = 17
+  ResultCodeInappropriateMatching        = 18
+  ResultCodeConstraintViolation          = 19
+  ResultCodeAttributeOrValueExists       = 20
+  ResultCodeInvalidAttributeSyntax       = 21
+  ResultCodeNoSuchObject                 = 32
+  ResultCodeAliasProblem                 = 33
+  ResultCodeInvalidDNSyntax              = 34
+  ResultCodeAliasDereferencingProblem    = 36
+  ResultCodeInappropriateAuthentication  = 48
+  ResultCodeInvalidCredentials           = 49
+  ResultCodeInsufficientAccessRights     = 50
+  ResultCodeBusy                         = 51
+  ResultCodeUnavailable                  = 52
+  ResultCodeUnwillingToPerform           = 53
+  ResultCodeNamingViolation              = 64
+  ResultCodeObjectClassViolation         = 65
+  ResultCodeNotAllowedOnNonLeaf          = 66
+  ResultCodeNotAllowedOnRDN              = 67
+  ResultCodeEntryAlreadyExists           = 68
+  ResultCodeObjectClassModsProhibited    = 69
+  ResultCodeAffectsMultipleDSAs          = 71
+  ResultCodeOther                        = 80
+
+  # https://tools.ietf.org/html/rfc4511#appendix-A.1
+  ResultCodesNonError = [
+    ResultCodeSuccess,
+    ResultCodeCompareFalse,
+    ResultCodeCompareTrue,
+    ResultCodeReferral,
+    ResultCodeSaslBindInProgress,
+  ]
+
+  # nonstandard list of "successful" result codes for searches
+  ResultCodesSearchSuccess = [
+    ResultCodeSuccess,
+    ResultCodeTimeLimitExceeded,
+    ResultCodeSizeLimitExceeded,
+  ]
+
+  # map of result code to human message
   ResultStrings = {
-    0 => "Success",
-    1 => "Operations Error",
-    2 => "Protocol Error",
-    3 => "Time Limit Exceeded",
-    4 => "Size Limit Exceeded",
-    10 => "Referral",
-    12 => "Unavailable crtical extension",
-    14 => "saslBindInProgress",
-    16 => "No Such Attribute",
-    17 => "Undefined Attribute Type",
-    20 => "Attribute or Value Exists",
-    32 => "No Such Object",
-    34 => "Invalid DN Syntax",
-    48 => "Inappropriate Authentication",
-    49 => "Invalid Credentials",
-    50 => "Insufficient Access Rights",
-    51 => "Busy",
-    52 => "Unavailable",
-    53 => "Unwilling to perform",
-    65 => "Object Class Violation",
-    68 => "Entry Already Exists"
+    ResultCodeSuccess                      => "Success",
+    ResultCodeOperationsError              => "Operations Error",
+    ResultCodeProtocolError                => "Protocol Error",
+    ResultCodeTimeLimitExceeded            => "Time Limit Exceeded",
+    ResultCodeSizeLimitExceeded            => "Size Limit Exceeded",
+    ResultCodeCompareFalse                 => "False Comparison",
+    ResultCodeCompareTrue                  => "True Comparison",
+    ResultCodeAuthMethodNotSupported       => "Auth Method Not Supported",
+    ResultCodeStrongerAuthRequired         => "Stronger Auth Needed",
+    ResultCodeReferral                     => "Referral",
+    ResultCodeAdminLimitExceeded           => "Admin Limit Exceeded",
+    ResultCodeUnavailableCriticalExtension => "Unavailable crtical extension",
+    ResultCodeConfidentialityRequired      => "Confidentiality Required",
+    ResultCodeSaslBindInProgress           => "saslBindInProgress",
+    ResultCodeNoSuchAttribute              => "No Such Attribute",
+    ResultCodeUndefinedAttributeType       => "Undefined Attribute Type",
+    ResultCodeInappropriateMatching        => "Inappropriate Matching",
+    ResultCodeConstraintViolation          => "Constraint Violation",
+    ResultCodeAttributeOrValueExists       => "Attribute or Value Exists",
+    ResultCodeInvalidAttributeSyntax       => "Invalide Attribute Syntax",
+    ResultCodeNoSuchObject                 => "No Such Object",
+    ResultCodeAliasProblem                 => "Alias Problem",
+    ResultCodeInvalidDNSyntax              => "Invalid DN Syntax",
+    ResultCodeAliasDereferencingProblem    => "Alias Dereferencing Problem",
+    ResultCodeInappropriateAuthentication  => "Inappropriate Authentication",
+    ResultCodeInvalidCredentials           => "Invalid Credentials",
+    ResultCodeInsufficientAccessRights     => "Insufficient Access Rights",
+    ResultCodeBusy                         => "Busy",
+    ResultCodeUnavailable                  => "Unavailable",
+    ResultCodeUnwillingToPerform           => "Unwilling to perform",
+    ResultCodeNamingViolation              => "Naming Violation",
+    ResultCodeObjectClassViolation         => "Object Class Violation",
+    ResultCodeNotAllowedOnNonLeaf          => "Not Allowed On Non-Leaf",
+    ResultCodeNotAllowedOnRDN              => "Not Allowed On RDN",
+    ResultCodeEntryAlreadyExists           => "Entry Already Exists",
+    ResultCodeObjectClassModsProhibited    => "ObjectClass Modifications Prohibited",
+    ResultCodeAffectsMultipleDSAs          => "Affects Multiple DSAs",
+    ResultCodeOther                        => "Other",
   }
 
-  module LdapControls
-    PagedResults = "1.2.840.113556.1.4.319" # Microsoft evil from RFC 2696
+  module LDAPControls
+    PAGED_RESULTS = "1.2.840.113556.1.4.319" # Microsoft evil from RFC 2696
+    SORT_REQUEST  = "1.2.840.113556.1.4.473"
+    SORT_RESPONSE = "1.2.840.113556.1.4.474"
+    DELETE_TREE   = "1.2.840.113556.1.4.805"
   end
 
   def self.result2string(code) #:nodoc:
@@ -345,6 +454,7 @@ class Net::LDAP
 
   attr_accessor :host
   attr_accessor :port
+  attr_accessor :hosts
   attr_accessor :base
 
   # Instantiate an object of type Net::LDAP to perform directory operations.
@@ -353,6 +463,8 @@ class Net::LDAP
   # described below. The following arguments are supported:
   # * :host => the LDAP server's IP-address (default 127.0.0.1)
   # * :port => the LDAP server's TCP port (default 389)
+  # * :hosts => an enumerable of pairs of hosts and corresponding ports with
+  #   which to attempt opening connections (default [[host, port]])
   # * :auth => a Hash containing authorization parameters. Currently
   #   supported values include: {:method => :anonymous} and {:method =>
   #   :simple, :username => your_user_name, :password => your_password }
@@ -364,28 +476,90 @@ 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.
+  # * :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 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
+  #     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
+    @hosts = args[:hosts]
     @verbose = false # Make this configurable with a switch on the class.
     @auth = args[:auth] || DefaultAuth
     @base = args[:base] || DefaultTreebase
-    encryption args[:encryption] # may be nil
+    @force_no_page = args[:force_no_page] || DefaultForceNoPage
+    @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
     end
 
+    @instrumentation_service = args[:instrumentation_service]
+
     # This variable is only set when we are created with LDAP::open. All of
     # our internal methods will connect using it, or else they will create
     # their own.
@@ -429,7 +603,7 @@ class Net::LDAP
     @auth = {
       :method => :simple,
       :username => username,
-      :password => password
+      :password => password,
     }
   end
   alias_method :auth, :authenticate
@@ -442,38 +616,12 @@ class Net::LDAP
   # 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
-  # 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.
-  #
-  # <i>[Note: a future version of Net::LDAP will support the STARTTLS LDAP
-  # control, which will enable encrypted communications on the same TCP port
-  # used for unencrypted connections.]</i>
+  # This method is deprecated.
+  #
   def encryption(args)
-    case args
-    when :simple_tls, :start_tls
-      args = { :method => args }
-    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
@@ -516,17 +664,22 @@ class Net::LDAP
   # response codes instead of a simple numeric code.
   #++
   def get_operation_result
+    result = @result
     os = OpenStruct.new
-    if @result.is_a?(Hash)
+    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.
-      os.code = (@result[:resultCode] || "").to_i
-      os.error_message = @result[:errorMessage]
-      os.matched_dn = @result[:matchedDN]
-    elsif @result
-      os.code = @result
+      os.code = (result[:resultCode] || "").to_i
+      os.error_message = result[:errorMessage]
+      os.matched_dn = result[:matchedDN]
+    elsif result
+      os.code = result
     else
-      os.code = 0
+      os.code = Net::LDAP::ResultCodeSuccess
     end
     os.message = Net::LDAP.result2string(os.code)
     os
@@ -553,18 +706,18 @@ class Net::LDAP
     # anything with the bind results. We then pass self to the caller's
     # block, where he will execute his LDAP operations. Of course they will
     # all generate auth failures if the bind was unsuccessful.
-    raise Net::LDAP::LdapError, "Open already in progress" if @open_connection
+    raise Net::LDAP::AlreadyOpenedError, "Open already in progress" if @open_connection
 
-    begin
-      @open_connection = Net::LDAP::Connection.new(:host => @host,
-                                                   :port => @port,
-                                                   :encryption =>
-                                                   @encryption)
-      @open_connection.bind(@auth)
-      yield self
-    ensure
-      @open_connection.close if @open_connection
-      @open_connection = nil
+    instrument "open.net_ldap" do |payload|
+      begin
+        @open_connection = new_connection
+        payload[:connection] = @open_connection
+        payload[:bind]       = @result = @open_connection.bind(@auth)
+        yield self
+      ensure
+        @open_connection.close if @open_connection
+        @open_connection = nil
+      end
     end
   end
 
@@ -582,6 +735,9 @@ class Net::LDAP
   #   Net::LDAP::SearchScope_WholeSubtree. Default is WholeSubtree.)
   # * :size (an integer indicating the maximum number of search entries to
   #   return. Default is zero, which signifies no limit.)
+  # * :time (an integer restricting the maximum time in seconds allowed for a search. Default is zero, no time limit RFC 4511 4.5.1.5)
+  # * :deref (one of: Net::LDAP::DerefAliases_Never, Net::LDAP::DerefAliases_Search,
+  #   Net::LDAP::DerefAliases_Find, Net::LDAP::DerefAliases_Always. Default is Never.)
   #
   # #search queries the LDAP server and passes <i>each entry</i> to the
   # caller-supplied block, as an object of type Net::LDAP::Entry. If the
@@ -623,31 +779,23 @@ class Net::LDAP
     return_result_set = args[:return_result] != false
     result_set = return_result_set ? [] : nil
 
-    if @open_connection
-      @result = @open_connection.search(args) { |entry|
-        result_set << entry if result_set
-        yield entry if block_given?
-      }
-    else
-      @result = 0
-      begin
-        conn = Net::LDAP::Connection.new(:host => @host, :port => @port,
-                                         :encryption => @encryption)
-        if (@result = conn.bind(args[:auth] || @auth)) == 0
-          @result = conn.search(args) { |entry|
-            result_set << entry if result_set
-            yield entry if block_given?
-          }
+    instrument "search.net_ldap", args do |payload|
+      @result = use_connection(args) do |conn|
+        conn.search(args) do |entry|
+          result_set << entry if result_set
+          yield entry if block_given?
         end
-      ensure
-        conn.close if conn
       end
-    end
 
-    if return_result_set
-      @result == 0 ? result_set : nil
-    else
-      @result == 0
+      if return_result_set
+        unless @result.nil?
+          if ResultCodesSearchSuccess.include?(@result.result_code)
+            result_set
+          end
+        end
+      else
+        @result.success?
+      end
     end
   end
 
@@ -709,19 +857,22 @@ class Net::LDAP
   # the documentation for #auth, the password parameter can be a Ruby Proc
   # instead of a String.
   def bind(auth = @auth)
-    if @open_connection
-      @result = @open_connection.bind(auth)
-    else
-      begin
-        conn = Connection.new(:host => @host, :port => @port,
-                              :encryption => @encryption)
-        @result = conn.bind(auth)
-      ensure
-        conn.close if conn
+    instrument "bind.net_ldap" do |payload|
+      if @open_connection
+        payload[:connection] = @open_connection
+        payload[:bind]       = @result = @open_connection.bind(auth)
+      else
+        begin
+          conn = new_connection
+          payload[:connection] = conn
+          payload[:bind]       = @result = conn.bind(auth)
+        ensure
+          conn.close if conn
+        end
       end
-    end
 
-    @result == 0
+      @result.success?
+    end
   end
 
   # #bind_as is for testing authentication credentials.
@@ -772,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]
@@ -780,7 +931,7 @@ class Net::LDAP
         result = rs if bind(:method => :simple, :username => dn,
                             :password => password)
       end
-    }
+    end
     result
   end
 
@@ -809,21 +960,12 @@ class Net::LDAP
   #    ldap.add(:dn => dn, :attributes => attr)
   #  end
   def add(args)
-    if @open_connection
-      @result = @open_connection.add(args)
-    else
-      @result = 0
-      begin
-        conn = Connection.new(:host => @host, :port => @port,
-                              :encryption => @encryption)
-        if (@result = conn.bind(args[:auth] || @auth)) == 0
-          @result = conn.add(args)
-        end
-      ensure
-        conn.close if conn
+    instrument "add.net_ldap", args do |payload|
+      @result = use_connection(args) do |conn|
+        conn.add(args)
       end
+      @result.success?
     end
-    @result == 0
   end
 
   # Modifies the attribute values of a particular entry on the LDAP
@@ -841,7 +983,7 @@ class Net::LDAP
   # The LDAP protocol provides a full and well thought-out set of operations
   # for changing the values of attributes, but they are necessarily somewhat
   # complex and not always intuitive. If these instructions are confusing or
-  # incomplete, please send us email or create a bug report on rubyforge.
+  # incomplete, please send us email or create an issue on GitHub.
   #
   # The :operations parameter to #modify takes an array of
   # operation-descriptors. Each individual operation is specified in one
@@ -849,9 +991,10 @@ class Net::LDAP
   # operations in order.
   #
   # Each of the operations appearing in the Array must itself be an Array
-  # with exactly three elements: an operator:: must be :add, :replace, or
-  # :delete an attribute name:: the attribute name (string or symbol) to
-  # modify a value:: either a string or an array of strings.
+  # with exactly three elements:
+  # an operator :: must be :add, :replace, or :delete
+  # an attribute name :: the attribute name (string or symbol) to modify
+  # a value :: either a string or an array of strings.
   #
   # The :add operator will, unsurprisingly, add the specified values to the
   # specified attribute. If the attribute does not already exist, :add will
@@ -894,34 +1037,63 @@ class Net::LDAP
   # may not get extended information that will tell you which one failed.
   # #modify has no notion of an atomic transaction. If you specify a chain
   # of modifications in one call to #modify, and one of them fails, the
-  # preceding ones will usually not be "rolled back, " resulting in a
+  # preceding ones will usually not be "rolled back", resulting in a
   # partial update. This is a limitation of the LDAP protocol, not of
   # Net::LDAP.
   #
   # The lack of transactional atomicity in LDAP means that you're usually
   # better off using the convenience methods #add_attribute,
-  # #replace_attribute, and #delete_attribute, which are are wrappers over
+  # #replace_attribute, and #delete_attribute, which are wrappers over
   # #modify. However, certain LDAP servers may provide concurrency
   # semantics, in which the several operations contained in a single #modify
   # call are not interleaved with other modification-requests received
   # simultaneously by the server. It bears repeating that this concurrency
   # does _not_ imply transactional atomicity, which LDAP does not provide.
   def modify(args)
-    if @open_connection
-      @result = @open_connection.modify(args)
-    else
-      @result = 0
-      begin
-        conn = Connection.new(:host => @host, :port => @port,
-                              :encryption => @encryption)
-        if (@result = conn.bind(args[:auth] || @auth)) == 0
-          @result = conn.modify(args)
-        end
-      ensure
-        conn.close if conn
+    instrument "modify.net_ldap", args do |payload|
+      @result = use_connection(args) do |conn|
+        conn.modify(args)
+      end
+      @result.success?
+    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
-    @result == 0
   end
 
   # Add a value to an attribute. Takes the full DN of the entry to modify,
@@ -978,21 +1150,12 @@ class Net::LDAP
   #
   # _Documentation_ _stub_
   def rename(args)
-    if @open_connection
-      @result = @open_connection.rename(args)
-    else
-      @result = 0
-      begin
-        conn = Connection.new(:host => @host, :port => @port,
-                              :encryption => @encryption)
-        if (@result = conn.bind(args[:auth] || @auth)) == 0
-          @result = conn.rename(args)
-        end
-      ensure
-        conn.close if conn
+    instrument "rename.net_ldap", args do |payload|
+      @result = use_connection(args) do |conn|
+        conn.rename(args)
       end
+      @result.success?
     end
-    @result == 0
   end
   alias_method :modify_rdn, :rename
 
@@ -1006,21 +1169,33 @@ class Net::LDAP
   #  dn = "mail=deleteme@example.com, ou=people, dc=example, dc=com"
   #  ldap.delete :dn => dn
   def delete(args)
-    if @open_connection
-      @result = @open_connection.delete(args)
-    else
-      @result = 0
-      begin
-        conn = Connection.new(:host => @host, :port => @port,
-                              :encryption => @encryption)
-        if (@result = conn.bind(args[:auth] || @auth)) == 0
-          @result = conn.delete(args)
-        end
-      ensure
-        conn.close
+    instrument "delete.net_ldap", args do |payload|
+      @result = use_connection(args) do |conn|
+        conn.delete(args)
       end
+      @result.success?
+    end
+  end
+
+  # Delete an entry from the LDAP directory along with all subordinate entries.
+  # the regular delete method will fail to delete an entry if it has subordinate
+  # 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)
+    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
-    @result == 0
   end
 
   # This method is experimental and subject to change. Return the rootDSE
@@ -1039,9 +1214,16 @@ class Net::LDAP
   def search_root_dse
     rs = search(:ignore_server_caps => true, :base => "",
                 :scope => SearchScope_BaseObject,
-                :attributes => [ :namingContexts, :supportedLdapVersion,
-                  :altServer, :supportedControl, :supportedExtension,
-                  :supportedFeatures, :supportedSASLMechanisms])
+                :attributes => [
+                  :altServer,
+                  :namingContexts,
+                  :supportedCapabilities,
+                  :supportedControl,
+                  :supportedExtension,
+                  :supportedFeatures,
+                  :supportedLdapVersion,
+                  :supportedSASLMechanisms,
+                ])
     (rs and rs.first) or Net::LDAP::Entry.new
   end
 
@@ -1092,473 +1274,93 @@ class Net::LDAP
   # MUST refactor the root_dse call out.
   #++
   def paged_searches_supported?
+    # active directory returns that it supports paged results. However
+    # it returns binary data in the rfc2696_cookie which throws an
+    # encoding exception breaking searching.
+    return false if @force_no_page
     @server_caps ||= search_root_dse
-    @server_caps[:supportedcontrol].include?(Net::LDAP::LdapControls::PagedResults)
+    @server_caps[:supportedcontrol].include?(Net::LDAP::LDAPControls::PAGED_RESULTS)
   end
-end # class LDAP
-
-# This is a private class used internally by the library. It should not
-# be called by user code.
-class Net::LDAP::Connection #:nodoc:
-  LdapVersion = 3
-  MaxSaslChallenges = 10
 
-  def initialize(server)
-    begin
-      @conn = TCPSocket.new(server[:host], server[:port])
-    rescue SocketError
-      raise Net::LDAP::LdapError, "No such address or other socket error."
-    rescue Errno::ECONNREFUSED
-      raise Net::LDAP::LdapError, "Server #{server[:host]} refused connection on port #{server[:port]}."
-    end
-
-    if server[:encryption]
-      setup_encryption server[:encryption]
-    end
-
-    yield self if block_given?
+  # Mask auth password
+  def inspect
+    inspected = super
+    inspected.gsub! @auth[:password], "*******" if @auth[:password]
+    inspected
   end
 
-  module GetbyteForSSLSocket
-    def getbyte
-      getc.ord
-    end
+  # Internal: Set @open_connection for testing
+  def connection=(connection)
+    @open_connection = connection
   end
 
-  def self.wrap_with_ssl(io)
-    raise Net::LDAP::LdapError, "OpenSSL is unavailable" unless Net::LDAP::HasOpenSSL
-    ctx = OpenSSL::SSL::SSLContext.new
-    conn = OpenSSL::SSL::SSLSocket.new(io, ctx)
-    conn.connect
-    conn.sync_close = true
+  private
 
-    conn.extend(GetbyteForSSLSocket) unless conn.respond_to?(:getbyte)
-
-    conn
-  end
-
-  #--
-  # Helper method called only from new, and only after we have a
-  # successfully-opened @conn instance variable, which is a TCP connection.
-  # Depending on the received arguments, we establish SSL, potentially
-  # replacing the value of @conn accordingly. Don't generate any errors here
-  # if no encryption is requested. DO raise Net::LDAP::LdapError objects if encryption
-  # is requested and we have trouble setting it up. That includes if OpenSSL
-  # is not set up on the machine. (Question: how does the Ruby OpenSSL
-  # wrapper react in that case?) DO NOT filter exceptions raised by the
-  # OpenSSL library. Let them pass back to the user. That should make it
-  # easier for us to debug the problem reports. Presumably (hopefully?) that
-  # will also produce recognizable errors if someone tries to use this on a
-  # machine without OpenSSL.
-  #
-  # The simple_tls method is intended as the simplest, stupidest, easiest
-  # solution for people who want nothing more than encrypted comms with the
-  # LDAP server. It doesn't do any server-cert validation and requires
-  # nothing in the way of key files and root-cert files, etc etc. OBSERVE:
-  # WE REPLACE the value of @conn, which is presumed to be a connected
-  # TCPSocket object.
-  #
-  # The start_tls method is supported by many servers over the standard LDAP
-  # port. It does not require an alternative port for encrypted
-  # communications, as with simple_tls. Thanks for Kouhei Sutou for
-  # generously contributing the :start_tls path.
-  #++
-  def setup_encryption(args)
-    case args[:method]
-    when :simple_tls
-      @conn = self.class.wrap_with_ssl(@conn)
-      # additional branches requiring server validation and peer certs, etc.
-      # go here.
-    when :start_tls
-      msgid = next_msgid.to_ber
-      request = [Net::LDAP::StartTlsOid.to_ber].to_ber_appsequence(Net::LDAP::PDU::ExtendedRequest)
-      request_pkt = [msgid, request].to_ber_sequence
-      @conn.write request_pkt
-      be = @conn.read_ber(Net::LDAP::AsnSyntax)
-      raise Net::LDAP::LdapError, "no start_tls result" if be.nil?
-      pdu = Net::LDAP::PDU.new(be)
-      raise Net::LDAP::LdapError, "no start_tls result" if pdu.nil?
-      if pdu.result_code.zero?
-        @conn = self.class.wrap_with_ssl(@conn)
-      else
-        raise Net::LDAP::LdapError, "start_tls failed: #{pdu.result_code}"
-      end
-    else
-      raise Net::LDAP::LdapError, "unsupported encryption method #{args[:method]}"
-    end
-  end
-
-  #--
-  # This is provided as a convenience method to make sure a connection
-  # object gets closed without waiting for a GC to happen. Clients shouldn't
-  # have to call it, but perhaps it will come in handy someday.
-  #++
-  def close
-    @conn.close
-    @conn = nil
-  end
-
-  def next_msgid
-    @msgid ||= 0
-    @msgid += 1
-  end
-
-  def bind(auth)
-    meth = auth[:method]
-    if [:simple, :anonymous, :anon].include?(meth)
-      bind_simple auth
-    elsif meth == :sasl
-      bind_sasl(auth)
-    elsif meth == :gss_spnego
-      bind_gss_spnego(auth)
+  # Yields an open connection if there is one, otherwise establishes a new
+  # connection, binds, and yields it. If binding fails, it will return the
+  # result from that, and :use_connection: will not yield at all. If not
+  # the return value is whatever is returned from the block.
+  def use_connection(args)
+    if @open_connection
+      yield @open_connection
     else
-      raise Net::LDAP::LdapError, "Unsupported auth method (#{meth})"
+      begin
+        conn = new_connection
+        result = conn.bind(args[:auth] || @auth)
+        return result unless result.result_code == Net::LDAP::ResultCodeSuccess
+        yield conn
+      ensure
+        conn.close if conn
+      end
     end
   end
 
-  #--
-  # Implements a simple user/psw authentication. Accessed by calling #bind
-  # with a method of :simple or :anonymous.
-  #++
-  def bind_simple(auth)
-    user, psw = if auth[:method] == :simple
-                  [auth[:username] || auth[:dn], auth[:password]]
-                else
-                  ["", ""]
-                end
-
-    raise Net::LDAP::LdapError, "Invalid binding information" unless (user && psw)
-
-    msgid = next_msgid.to_ber
-    request = [LdapVersion.to_ber, user.to_ber,
-      psw.to_ber_contextspecific(0)].to_ber_appsequence(0)
-    request_pkt = [msgid, request].to_ber_sequence
-    @conn.write request_pkt
-
-    (be = @conn.read_ber(Net::LDAP::AsnSyntax) and pdu = Net::LDAP::PDU.new(be)) or raise Net::LDAP::LdapError, "no bind result"
-
-    pdu.result_code
-  end
-
-  #--
-  # Required parameters: :mechanism, :initial_credential and
-  # :challenge_response
-  #
-  # Mechanism is a string value that will be passed in the SASL-packet's
-  # "mechanism" field.
-  #
-  # Initial credential is most likely a string. It's passed in the initial
-  # BindRequest that goes to the server. In some protocols, it may be empty.
-  #
-  # Challenge-response is a Ruby proc that takes a single parameter and
-  # returns an object that will typically be a string. The
-  # challenge-response block is called when the server returns a
-  # BindResponse with a result code of 14 (saslBindInProgress). The
-  # challenge-response block receives a parameter containing the data
-  # returned by the server in the saslServerCreds field of the LDAP
-  # BindResponse packet. The challenge-response block may be called multiple
-  # times during the course of a SASL authentication, and each time it must
-  # return a value that will be passed back to the server as the credential
-  # data in the next BindRequest packet.
-  #++
-  def bind_sasl(auth)
-    mech, cred, chall = auth[:mechanism], auth[:initial_credential],
-      auth[:challenge_response]
-    raise Net::LDAP::LdapError, "Invalid binding information" unless (mech && cred && chall)
-
-    n = 0
-    loop {
-      msgid = next_msgid.to_ber
-      sasl = [mech.to_ber, cred.to_ber].to_ber_contextspecific(3)
-      request = [LdapVersion.to_ber, "".to_ber, sasl].to_ber_appsequence(0)
-      request_pkt = [msgid, request].to_ber_sequence
-      @conn.write request_pkt
-
-      (be = @conn.read_ber(Net::LDAP::AsnSyntax) and pdu = Net::LDAP::PDU.new(be)) or raise Net::LDAP::LdapError, "no bind result"
-      return pdu.result_code unless pdu.result_code == 14 # saslBindInProgress
-      raise Net::LDAP::LdapError, "sasl-challenge overflow" if ((n += 1) > MaxSaslChallenges)
-
-      cred = chall.call(pdu.result_server_sasl_creds)
+  # Establish a new connection to the LDAP server
+  def new_connection
+    connection = Net::LDAP::Connection.new \
+      :host                    => @host,
+      :port                    => @port,
+      :hosts                   => @hosts,
+      :encryption              => @encryption,
+      :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 Net::LDAP::LdapError, "why are we here?"
-  end
-  private :bind_sasl
-
-  #--
-  # PROVISIONAL, only for testing SASL implementations. DON'T USE THIS YET.
-  # Uses Kohei Kajimoto's Ruby/NTLM. We have to find a clean way to
-  # integrate it without introducing an external dependency.
-  #
-  # This authentication method is accessed by calling #bind with a :method
-  # parameter of :gss_spnego. It requires :username and :password
-  # attributes, just like the :simple authentication method. It performs a
-  # GSS-SPNEGO authentication with the server, which is presumed to be a
-  # Microsoft Active Directory.
-  #++
-  def bind_gss_spnego(auth)
-    require 'ntlm'
-
-    user, psw = [auth[:username] || auth[:dn], auth[:password]]
-    raise Net::LDAP::LdapError, "Invalid binding information" unless (user && psw)
-
-    nego = proc { |challenge|
-      t2_msg = NTLM::Message.parse(challenge)
-      t3_msg = t2_msg.response({ :user => user, :password => psw },
-                               { :ntlmv2 => true })
-      t3_msg.serialize
-    }
-
-    bind_sasl(:method => :sasl, :mechanism => "GSS-SPNEGO",
-              :initial_credential => NTLM::Message::Type1.new.serialize,
-              :challenge_response => nego)
-  end
-  private :bind_gss_spnego
-
-  #--
-  # Alternate implementation, this yields each search entry to the caller as
-  # it are received.
-  #
-  # TODO: certain search parameters are hardcoded.
-  # TODO: if we mis-parse the server results or the results are wrong, we
-  # can block forever. That's because we keep reading results until we get a
-  # type-5 packet, which might never come. We need to support the time-limit
-  # in the protocol.
-  #++
-  def search(args = {})
-    search_filter = (args && args[:filter]) ||
-      Net::LDAP::Filter.eq("objectclass", "*")
-    search_filter = Net::LDAP::Filter.construct(search_filter) if search_filter.is_a?(String)
-    search_base = (args && args[:base]) || "dc=example, dc=com"
-    search_attributes = ((args && args[:attributes]) || []).map { |attr| attr.to_s.to_ber}
-    return_referrals = args && args[:return_referrals] == true
-    sizelimit = (args && args[:size].to_i) || 0
-    raise Net::LDAP::LdapError, "invalid search-size" unless sizelimit >= 0
-    paged_searches_supported = (args && args[:paged_searches_supported])
-
-    attributes_only = (args and args[:attributes_only] == true)
-    scope = args[:scope] || Net::LDAP::SearchScope_WholeSubtree
-    raise Net::LDAP::LdapError, "invalid search scope" unless Net::LDAP::SearchScopes.include?(scope)
-
-    # An interesting value for the size limit would be close to A/D's
-    # built-in page limit of 1000 records, but openLDAP newer than version
-    # 2.2.0 chokes on anything bigger than 126. You get a silent error that
-    # is easily visible by running slapd in debug mode. Go figure.
-    #
-    # Changed this around 06Sep06 to support a caller-specified search-size
-    # limit. Because we ALWAYS do paged searches, we have to work around the
-    # problem that it's not legal to specify a "normal" sizelimit (in the
-    # body of the search request) that is larger than the page size we're
-    # requesting. Unfortunately, I have the feeling that this will break
-    # with LDAP servers that don't support paged searches!!!
-    #
-    # (Because we pass zero as the sizelimit on search rounds when the
-    # remaining limit is larger than our max page size of 126. In these
-    # cases, I think the caller's search limit will be ignored!)
-    #
-    # CONFIRMED: This code doesn't work on LDAPs that don't support paged
-    # searches when the size limit is larger than 126. We're going to have
-    # to do a root-DSE record search and not do a paged search if the LDAP
-    # doesn't support it. Yuck.
-    rfc2696_cookie = [126, ""]
-    result_code = 0
-    n_results = 0
-
-    loop {
-      # should collect this into a private helper to clarify the structure
-      query_limit = 0
-      if sizelimit > 0
-        if paged_searches_supported
-          query_limit = (((sizelimit - n_results) < 126) ? (sizelimit -
-                                                            n_results) : 0)
-        else
-          query_limit = sizelimit
-        end
-      end
-
-      request = [
-        search_base.to_ber,
-        scope.to_ber_enumerated,
-        0.to_ber_enumerated,
-        query_limit.to_ber, # size limit
-        0.to_ber,
-        attributes_only.to_ber,
-        search_filter.to_ber,
-        search_attributes.to_ber_sequence
-      ].to_ber_appsequence(3)
-
-      controls = []
-      controls <<
-        [
-          Net::LDAP::LdapControls::PagedResults.to_ber,
-          # Criticality MUST be false to interoperate with normal LDAPs.
-          false.to_ber,
-          rfc2696_cookie.map{ |v| v.to_ber}.to_ber_sequence.to_s.to_ber
-        ].to_ber_sequence if paged_searches_supported
-      controls = controls.empty? ? nil : controls.to_ber_contextspecific(0)
-
-      pkt = [next_msgid.to_ber, request, controls].compact.to_ber_sequence
-      @conn.write pkt
-
-      result_code = 0
-      controls = []
-
-      while (be = @conn.read_ber(Net::LDAP::AsnSyntax)) && (pdu = Net::LDAP::PDU.new(be))
-        case pdu.app_tag
-        when 4 # search-data
-          n_results += 1
-          yield pdu.search_entry if block_given?
-        when 19 # search-referral
-          if return_referrals
-            if block_given?
-              se = Net::LDAP::Entry.new
-              se[:search_referrals] = (pdu.search_referrals || [])
-              yield se
-            end
-          end
-        when 5 # search-result
-          result_code = pdu.result_code
-          controls = pdu.result_controls
-          if return_referrals && result_code == 10
-            if block_given?
-              se = Net::LDAP::Entry.new
-              se[:search_referrals] = (pdu.search_referrals || [])
-              yield se
-            end
-          end
-          break
-        else
-          raise Net::LDAP::LdapError, "invalid response-type in search: #{pdu.app_tag}"
-        end
-      end
-
-      # When we get here, we have seen a type-5 response. If there is no
-      # error AND there is an RFC-2696 cookie, then query again for the next
-      # page of results. If not, we're done. Don't screw this up or we'll
-      # break every search we do.
-      #
-      # Noticed 02Sep06, look at the read_ber call in this loop, shouldn't
-      # that have a parameter of AsnSyntax? Does this just accidentally
-      # work? According to RFC-2696, the value expected in this position is
-      # of type OCTET STRING, covered in the default syntax supported by
-      # read_ber, so I guess we're ok.
-      more_pages = false
-      if result_code == 0 and controls
-        controls.each do |c|
-          if c.oid == Net::LDAP::LdapControls::PagedResults
-            # just in case some bogus server sends us more than 1 of these.
-            more_pages = false
-            if c.value and c.value.length > 0
-              cookie = c.value.read_ber[1]
-              if cookie and cookie.length > 0
-                rfc2696_cookie[1] = cookie
-                more_pages = true
-              end
-            end
-          end
-        end
-      end
-
-      break unless more_pages
-    } # loop
-
-    result_code
+    raise e
   end
 
-  MODIFY_OPERATIONS = { #:nodoc:
-    :add => 0,
-    :delete => 1,
-    :replace => 2
-  }
+  # 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
 
-  def self.modify_ops(operations)
-    ops = []
-    if operations
-      operations.each { |op, attrib, values|
-        # TODO, fix the following line, which gives a bogus error if the
-        # opcode is invalid.
-        op_ber = MODIFY_OPERATIONS[op.to_sym].to_ber_enumerated
-        values = [ values ].flatten.map { |v| v.to_ber if v }.to_ber_set
-        values = [ attrib.to_s.to_ber, values ].to_ber_sequence
-        ops << [ op_ber, values ].to_ber
-      }
+    case method = args.to_sym
+    when :simple_tls, :start_tls
+      { :method => method, :tls_options => {} }
     end
-    ops
   end
 
-  #--
-  # TODO: need to support a time limit, in case the server fails to respond.
-  # TODO: We're throwing an exception here on empty DN. Should return a
-  # proper error instead, probaby from farther up the chain.
-  # TODO: If the user specifies a bogus opcode, we'll throw a confusing
-  # error here ("to_ber_enumerated is not defined on nil").
-  #++
-  def modify(args)
-    modify_dn = args[:dn] or raise "Unable to modify empty DN"
-    ops = self.class.modify_ops args[:operations]
-    request = [ modify_dn.to_ber,
-      ops.to_ber_sequence ].to_ber_appsequence(6)
-    pkt = [ next_msgid.to_ber, request ].to_ber_sequence
-    @conn.write pkt
-
-    (be = @conn.read_ber(Net::LDAP::AsnSyntax)) && (pdu = Net::LDAP::PDU.new(be)) && (pdu.app_tag == 7) or raise Net::LDAP::LdapError, "response missing or invalid"
-    pdu.result_code
-  end
-
-  #--
-  # TODO: need to support a time limit, in case the server fails to respond.
-  # Unlike other operation-methods in this class, we return a result hash
-  # rather than a simple result number. This is experimental, and eventually
-  # we'll want to do this with all the others. The point is to have access
-  # to the error message and the matched-DN returned by the server.
-  #++
-  def add(args)
-    add_dn = args[:dn] or raise Net::LDAP::LdapError, "Unable to add empty DN"
-    add_attrs = []
-    a = args[:attributes] and a.each { |k, v|
-      add_attrs << [ k.to_s.to_ber, Array(v).map { |m| m.to_ber}.to_ber_set ].to_ber_sequence
-    }
-
-    request = [add_dn.to_ber, add_attrs.to_ber_sequence].to_ber_appsequence(8)
-    pkt = [next_msgid.to_ber, request].to_ber_sequence
-    @conn.write pkt
-
-    (be = @conn.read_ber(Net::LDAP::AsnSyntax)) && (pdu = Net::LDAP::PDU.new(be)) && (pdu.app_tag == 9) or raise Net::LDAP::LdapError, "response missing or invalid"
-    pdu.result_code
-  end
-
-  #--
-  # TODO: need to support a time limit, in case the server fails to respond.
-  #++
-  def rename args
-    old_dn = args[:olddn] or raise "Unable to rename empty DN"
-    new_rdn = args[:newrdn] or raise "Unable to rename to empty RDN"
-    delete_attrs = args[:delete_attributes] ? true : false
-    new_superior = args[:new_superior]
-
-    request = [old_dn.to_ber, new_rdn.to_ber, delete_attrs.to_ber]
-    request << new_superior.to_ber unless new_superior == nil
-
-    pkt = [next_msgid.to_ber, request.to_ber_appsequence(12)].to_ber_sequence
-    @conn.write pkt
-
-    (be = @conn.read_ber(Net::LDAP::AsnSyntax)) &&
-    (pdu = Net::LDAP::PDU.new( be )) && (pdu.app_tag == 13) or
-    raise Net::LDAP::LdapError.new( "response missing or invalid" )
-    pdu.result_code
+  # 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
 
-  #--
-  # TODO, need to support a time limit, in case the server fails to respond.
-  #++
-  def delete(args)
-    dn = args[:dn] or raise "Unable to delete empty DN"
-
-    request = dn.to_s.to_ber_application_string(10)
-    pkt = [next_msgid.to_ber, request].to_ber_sequence
-    @conn.write pkt
-
-    (be = @conn.read_ber(Net::LDAP::AsnSyntax)) && (pdu = Net::LDAP::PDU.new(be)) && (pdu.app_tag == 11) or raise Net::LDAP::LdapError, "response missing or invalid"
-    pdu.result_code
-  end
-end # class Connection
+end # class LDAP