net-ldap 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 487807bc08da7baeb4941090020468a8e60fe14a
-  data.tar.gz: 047ccb6638a81c96eb1bfca1a684726a71bfc1a8
+  metadata.gz: f9fc3d7a463a0f673de926b440e144eae66937a4
+  data.tar.gz: 2d921f1be37ff33c20100650642f1123fcd2c161
 SHA512:
-  metadata.gz: 6d02d5a7af488a5f7ee8b8050c5d281d6e76b7c40baeb1a1275a18b103d2f76cf0fea8dfa865efe2ce243d92b87c3d6abdfa1b47615cf95fb5cd5e9b9806e70a
-  data.tar.gz: 380cc5961a9a85a1d196203b6712061b5c8b8a4c1008dcfcee67556029269e264d2d7463e2e98572c06020dbae44dbb8ace34f06d584d33a9f1b5f6169f90d9d
+  metadata.gz: 803d644ca0fe9b7314df587e68a0ecc7f01f34316d30fd4a926a09dfc4e3ab7e73b388854f9f4eecc78c9b07817d21a0b342e893422d21b8a682c35dcf4a8fb1
+  data.tar.gz: e5143361c56f7c60cfe7272c054860403ec53812660730e141688be9fb56adf32b0121ae1d5e27c4a076a963b07b509db96e7a8cc43fa0eec7d5cf0b1e92dcdd

data/.gitignore

@@ -0,0 +1,7 @@
+*~
+*.swp
+.rvmrc
+pkg/
+doc/
+publish/
+Gemfile.lock

data/.travis.yml

@@ -2,9 +2,27 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
+  - 2.1.2
+  # optional
   - jruby-19mode
   - rbx-19mode
+  - rbx-2
+
+env:
+  - INTEGRATION=openldap
+
+install:
+  - if [ "$INTEGRATION" = "openldap" ]; then ./script/install-openldap; fi
+  - bundle install
+
+script: bundle exec rake
+
 matrix:
   allow_failures:
     - rvm: jruby-19mode
-script: bundle exec rake spec
+    - rvm: rbx-19mode
+    - rvm: rbx-2
+  fast_finish: true
+
+notifications:
+  email: false

data/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contribution guide
+
+Thank you for using net-ldap. If you'd like to help, keep these guidelines in
+mind.
+
+## Submitting a New Issue
+
+If you find a bug, or would like to propose an idea, file a [new issue][issues].
+Include as many details as possible:
+
+- Version of net-ldap gem
+- LDAP server version
+- Queries, connection information, any other input
+- output or error messages
+
+## Sending a Pull Request
+
+[Pull requests][pr] are always welcome!
+
+Check out [the project's issues list][issues] for ideas on what could be improved.
+
+Before sending, please add tests and ensure the test suite passes.
+
+To run the full suite:
+
+  `bundle exec rake`
+
+To run a specific test file:
+
+  `bundle exec ruby test/test_ldap.rb`
+
+To run a specific test:
+
+  `bundle exec ruby test/test_ldap.rb -n test_instrument_bind`
+
+Pull requests will trigger automatic continuous integration builds on
+[TravisCI][travis]. To run integration tests locally, see the `test/support`
+folder.
+
+## Styleguide
+
+```ruby
+# 1.9+ style hashes
+{key: "value"}
+
+# Multi-line arguments with `\`
+MyClass.new \
+  foo: 'bar',
+  baz: 'garply'
+```
+
+[issues]: https://github.com/ruby-net-ldap/ruby-net-ldap/issues
+[pr]: https://help.github.com/articles/using-pull-requests
+[travis]: https://travis-ci.org/ruby-ldap/ruby-net-ldap

data/Hacking.rdoc

@@ -40,8 +40,8 @@ modification to +Contributors.rdoc+ to add yourself.
 
 == Tests
 
-The Net::LDAP team uses RSpec for unit testing; all changes must have rspec
-tests for any new or changed features.
+The Net::LDAP team uses [Minitest](http://docs.seattlerb.org/minitest/) for unit
+testing; all changes must have tests for any new or changed features.
 
 Your changes should have been tested against at least one real LDAP server; the
 current tests are not sufficient to find all possible bugs. It's unlikely that
@@ -57,8 +57,6 @@ installed using RubyGems.
 
 * *hoe*
 * *hoe-git*
-* *metaid*
-* *rspec*
 * *flexmock*
 
 == Participation

data/History.rdoc

@@ -1,3 +1,40 @@
+=== Net::LDAP 0.9.0
+* Major changes:
+  * Dropped support for ruby 1.8.7, ruby >= 1.9.3 now required
+* Major enhancements:
+  * Add support for search time limit parameter
+  * Instrument received messages, PDU parsing
+* Minor enhancments:
+  * Add support for querying ActiveDirectory capabilities from root dse
+* Bug fixes:
+  * Fix reads for multiple concurrent requests with shared, open connections mixing up the results
+  * Fix search size option
+  * Fix BER encoding bug
+* Code clean-up:
+  * Added integration test suite
+  * Switch to minitest
+
+* Details
+  * #150 Support querying ActiveDirectory capabilities when searching root dse
+  * #142 Encode true as xFF
+  * #124, #145, #146, #152 Cleanup gemspec
+  * #138, #144 Track response messages by message id
+  * #141 Magic number/constant cleanup
+  * #119, #129, #130, #132, #133, #137 Integration tests
+  * #115 Search timeout support
+  * #140 Fix search size option
+  * #139 Cleanup and inline documentation for Net::LDAP::Connection#search
+  * #131 Instrumentation
+  * #116 Refactor Connection#write
+  * #126 Update gitignore
+  * #128 Fix whitespace
+  * #113, #121 Switch to minitest
+  * #123 Base64 encoded dn
+  * #114 Separate file for Net::LDAP::Connection
+  * #104 Parse version spec in LDIF datasets
+  * #106 ldap.modify doc fixes
+  * #111 Fix test deprecations
+
 === Net::LDAP 0.5.0 / 2013-07-22
 * Major changes:
   * Required Ruby version is >=1.9.3

data/Manifest.txt

@@ -1,5 +1,3 @@
-.autotest
-.rspec
 .travis.yml
 Contributors.rdoc
 Gemfile
@@ -9,7 +7,6 @@ License.rdoc
 Manifest.txt
 README.rdoc
 Rakefile
-autotest/discover.rb
 lib/net-ldap.rb
 lib/net/ber.rb
 lib/net/ber/ber_parser.rb
@@ -32,7 +29,6 @@ lib/net/ldap/version.rb
 lib/net/snmp.rb
 net-ldap.gemspec
 spec/integration/ssl_ber_spec.rb
-spec/spec.opts
 spec/spec_helper.rb
 spec/unit/ber/ber_spec.rb
 spec/unit/ber/core_ext/array_spec.rb

data/README.rdoc

@@ -37,6 +37,14 @@ sources.
 
 Simply require either 'net-ldap' or 'net/ldap'.
 
+== Release
+
+This section is for gem maintainers to cut a new version of the gem.
+
+* Update lib/html/pipeline/version.rb to next version number X.X.X following {semver}(http://semver.org/).
+* Update CHANGELOG.md. Get latest changes with `git log --oneline vLAST_RELEASE..HEAD | grep Merge`
+* On the master branch, run `script/release`
+
 :include: Contributors.rdoc
 
 :include: License.rdoc

data/Rakefile

@@ -30,9 +30,7 @@ Hoe.spec 'net-ldap' do |spec|
 
   spec.extra_dev_deps << [ "hoe-git", "~> 1" ]
   spec.extra_dev_deps << [ "hoe-gemspec", "~> 1" ]
-  spec.extra_dev_deps << [ "metaid", "~> 1" ]
   spec.extra_dev_deps << [ "flexmock", ">= 1.3.0" ]
-  spec.extra_dev_deps << [ "rspec", "~> 2.0" ]
 
   spec.clean_globs << "coverage"
 
@@ -70,7 +68,7 @@ namespace :old do
   end
 end
 
-desc "Run a full set of integration and unit tests" 
+desc "Run a full set of integration and unit tests"
 task :cruise => [:test, :spec]
 
 # vim: syntax=ruby

data/lib/net/ber/core_ext.rb

@@ -28,35 +28,35 @@ end
 
 require 'net/ber/core_ext/array'
 # :stopdoc:
-class Array 
+class Array
   include Net::BER::Extensions::Array
 end
 # :startdoc:
 
 require 'net/ber/core_ext/bignum'
 # :stopdoc:
-class Bignum 
+class Bignum
   include Net::BER::Extensions::Bignum
 end
 # :startdoc:
 
 require 'net/ber/core_ext/fixnum'
 # :stopdoc:
-class Fixnum 
+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'
 # :stopdoc:
-class FalseClass 
+class FalseClass
   include Net::BER::Extensions::FalseClass
 end
 # :startdoc:

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

@@ -16,13 +16,13 @@ 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
+  ##
+  # 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)

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

@@ -24,6 +24,7 @@ require 'net/ldap/dataset'
 require 'net/ldap/password'
 require 'net/ldap/entry'
 require 'net/ldap/instrumentation'
+require 'net/ldap/connection'
 require 'net/ldap/version'
 
 # == Quick-start for the Impatient
@@ -316,33 +317,107 @@ class Net::LDAP
   DefaultPort = 389
   DefaultAuth = { :method => :anonymous }
   DefaultTreebase = "dc=com"
-	DefaultForceNoPage = false
+  DefaultForceNoPage = false
 
   StartTlsOid = "1.3.6.1.4.1.1466.20037"
 
+  # 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",
-    19 => "Constraint Violation",
-    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
@@ -397,7 +472,7 @@ class Net::LDAP
     @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
+    @force_no_page = args[:force_no_page] || DefaultForceNoPage
     encryption args[:encryption] # may be nil
 
     if pr = @auth[:password] and pr.respond_to?(:call)
@@ -485,9 +560,9 @@ class Net::LDAP
   # 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>
+  # 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.
   def encryption(args)
     case args
     when :simple_tls, :start_tls
@@ -548,7 +623,7 @@ class Net::LDAP
     elsif result
       os.code = result
     else
-      os.code = 0
+      os.code = Net::LDAP::ResultCodeSuccess
     end
     os.message = Net::LDAP.result2string(os.code)
     os
@@ -609,6 +684,7 @@ 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.)
   #
@@ -665,7 +741,7 @@ class Net::LDAP
             :port                    => @port,
             :encryption              => @encryption,
             :instrumentation_service => @instrumentation_service
-          if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
+          if (@result = conn.bind(args[:auth] || @auth)).result_code == Net::LDAP::ResultCodeSuccess
             @result = conn.search(args) { |entry|
               result_set << entry if result_set
               yield entry if block_given?
@@ -677,7 +753,11 @@ class Net::LDAP
       end
 
       if return_result_set
-        (!@result.nil? && @result.result_code == 0) ? result_set : nil
+        unless @result.nil?
+          if ResultCodesSearchSuccess.include?(@result.result_code)
+            result_set
+          end
+        end
       else
         @result.success?
       end
@@ -860,7 +940,7 @@ class Net::LDAP
             :port                    => @port,
             :encryption              => @encryption,
             :instrumentation_service => @instrumentation_service
-          if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
+          if (@result = conn.bind(args[:auth] || @auth)).result_code == Net::LDAP::ResultCodeSuccess
             @result = conn.add(args)
           end
         ensure
@@ -894,9 +974,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
@@ -939,13 +1020,13 @@ 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
@@ -963,7 +1044,7 @@ class Net::LDAP
             :port                    => @port,
             :encryption              => @encryption,
             :instrumentation_service => @instrumentation_service
-          if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
+          if (@result = conn.bind(args[:auth] || @auth)).result_code == Net::LDAP::ResultCodeSuccess
             @result = conn.modify(args)
           end
         ensure
@@ -1040,7 +1121,7 @@ class Net::LDAP
             :port                    => @port,
             :encryption              => @encryption,
             :instrumentation_service => @instrumentation_service
-          if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
+          if (@result = conn.bind(args[:auth] || @auth)).result_code == Net::LDAP::ResultCodeSuccess
             @result = conn.rename(args)
           end
         ensure
@@ -1073,7 +1154,7 @@ class Net::LDAP
             :port                    => @port,
             :encryption              => @encryption,
             :instrumentation_service => @instrumentation_service
-          if (@result = conn.bind(args[:auth] || @auth)).result_code == 0
+          if (@result = conn.bind(args[:auth] || @auth)).result_code == Net::LDAP::ResultCodeSuccess
             @result = conn.delete(args)
           end
         ensure
@@ -1113,9 +1194,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
 
@@ -1166,585 +1254,11 @@ 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
+    # 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::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:
-  include Net::LDAP::Instrumentation
-
-  LdapVersion = 3
-  MaxSaslChallenges = 10
-
-  def initialize(server)
-    @instrumentation_service = server[:instrumentation_service]
-
-    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?
-  end
-
-  module GetbyteForSSLSocket
-    def getbyte
-      getc.ord
-    end
-  end
-
-  module FixSSLSocketSyncClose
-    def close
-      super
-      io.close
-    end
-  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
-
-    # Doesn't work:
-    # conn.sync_close = true
-
-    conn.extend(GetbyteForSSLSocket) unless conn.respond_to?(:getbyte)
-    conn.extend(FixSSLSocketSyncClose)
-
-    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_contextspecific(0)].to_ber_appsequence(Net::LDAP::PDU::ExtendedRequest)
-      request_pkt = [msgid, request].to_ber_sequence
-      write request_pkt
-      be = read
-      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
-
-  # Internal: Reads and parses data from the configured connection.
-  #
-  # - syntax: the BER syntax to use to parse the read data with
-  #
-  # Returns basic BER objects.
-  def read(syntax = Net::LDAP::AsnSyntax)
-    instrument "read.net_ldap_connection", :syntax => syntax do |payload|
-      @conn.read_ber(syntax) do |id, content_length|
-        payload[:object_type_id] = id
-        payload[:content_length] = content_length
-      end
-    end
-  end
-  private :read
-
-  # Internal: Writes the given packet to the configured connection.
-  #
-  # - packet: the BER data packet to write on the socket.
-  #
-  # Returns the return value from writing to the connection, which in some
-  # cases is the Integer number of bytes written to the socket.
-  def write(packet)
-    instrument "write.net_ldap_connection" do |payload|
-      payload[:content_length] = @conn.write(packet)
-    end
-  end
-  private :write
-
-  def next_msgid
-    @msgid ||= 0
-    @msgid += 1
-  end
-
-  def bind(auth)
-    instrument "bind.net_ldap_connection" do |payload|
-      payload[:method] = 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)
-      else
-        raise Net::LDAP::LdapError, "Unsupported auth method (#{meth})"
-      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
-    write request_pkt
-
-    (be = read and pdu = Net::LDAP::PDU.new(be)) or raise Net::LDAP::LdapError, "no bind result"
-
-    pdu
-  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
-      write request_pkt
-
-      (be = read and pdu = Net::LDAP::PDU.new(be)) or raise Net::LDAP::LdapError, "no bind result"
-      return pdu 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)
-    }
-
-    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
-
-
-  #--
-  # Allow the caller to specify a sort control
-  #
-  # The format of the sort control needs to be:
-  #
-  # :sort_control => ["cn"]  # just a string
-  # or
-  # :sort_control => [["cn", "matchingRule", true]] #attribute, matchingRule, direction (true / false)
-  # or
-  # :sort_control => ["givenname","sn"] #multiple strings or arrays
-  #
-  def encode_sort_controls(sort_definitions)
-    return sort_definitions unless sort_definitions
-
-    sort_control_values = sort_definitions.map do |control|
-      control = Array(control) # if there is only an attribute name as a string then infer the orderinrule and reverseorder
-      control[0] = String(control[0]).to_ber,
-      control[1] = String(control[1]).to_ber,
-      control[2] = (control[2] == true).to_ber
-      control.to_ber_sequence
-    end
-    sort_control = [
-      Net::LDAP::LDAPControls::SORT_REQUEST.to_ber,
-      false.to_ber,
-      sort_control_values.to_ber_sequence.to_s.to_ber
-    ].to_ber_sequence
-  end
-
-  #--
-  # 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)
-
-    sort_control = encode_sort_controls(args.fetch(:sort_controls){ false })
-
-	deref = args[:deref] || Net::LDAP::DerefAliases_Never
-	raise Net::LDAP::LdapError.new( "invalid alias dereferencing value" ) unless Net::LDAP::DerefAliasesArray.include?(deref)
-
-
-    # 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_pdu = nil
-    n_results = 0
-
-    instrument "search.net_ldap_connection",
-               :filter     => search_filter,
-               :base       => search_base,
-               :scope      => scope,
-               :limit      => sizelimit,
-               :sort       => sort_control,
-               :referrals  => return_referrals,
-               :deref      => deref,
-               :attributes => search_attributes do |payload|
-      loop do
-        # 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,
-          deref.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)
-
-  			# rfc2696_cookie sometimes contains binary data from Microsoft Active Directory
-  			# this breaks when calling to_ber. (Can't force binary data to UTF-8)
-  			# we have to disable paging (even though server supports it) to get around this...
-
-        controls = []
-        controls <<
-          [
-            Net::LDAP::LDAPControls::PAGED_RESULTS.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 << sort_control if sort_control
-        controls = controls.empty? ? nil : controls.to_ber_contextspecific(0)
-
-        pkt = [next_msgid.to_ber, request, controls].compact.to_ber_sequence
-        write pkt
-
-        result_pdu = nil
-        controls = []
-
-        while (be = read) && (pdu = Net::LDAP::PDU.new(be))
-          case pdu.app_tag
-          when Net::LDAP::PDU::SearchReturnedData
-            n_results += 1
-            yield pdu.search_entry if block_given?
-          when Net::LDAP::PDU::SearchResultReferral
-            if return_referrals
-              if block_given?
-                se = Net::LDAP::Entry.new
-                se[:search_referrals] = (pdu.search_referrals || [])
-                yield se
-              end
-            end
-          when Net::LDAP::PDU::SearchResult
-            result_pdu = pdu
-            controls = pdu.result_controls
-            if return_referrals && pdu.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
-
-        # count number of pages of results
-        payload[:page_count] ||= 0
-        payload[:page_count]  += 1
-
-        # 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_pdu.result_code == 0 and controls
-          controls.each do |c|
-            if c.oid == Net::LDAP::LDAPControls::PAGED_RESULTS
-              # 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
-      end # loop
-
-      # track total result count
-      payload[:result_count] = n_results
-
-      result_pdu || OpenStruct.new(:status => :failure, :result_code => 1, :message => "Invalid search")
-    end # instrument
-  end
-
-  MODIFY_OPERATIONS = { #:nodoc:
-    :add => 0,
-    :delete => 1,
-    :replace => 2
-  }
-
-  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
-      }
-    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
-    write pkt
-
-    (be = read) && (pdu = Net::LDAP::PDU.new(be)) && (pdu.app_tag == Net::LDAP::PDU::ModifyResponse) or raise Net::LDAP::LdapError, "response missing or invalid"
-
-    pdu
-  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
-    write pkt
-
-    (be = read) &&
-      (pdu = Net::LDAP::PDU.new(be)) &&
-      (pdu.app_tag == Net::LDAP::PDU::AddResponse) or
-      raise Net::LDAP::LdapError, "response missing or invalid"
-
-    pdu
-  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_contextspecific(0) unless new_superior == nil
-
-    pkt = [next_msgid.to_ber, request.to_ber_appsequence(12)].to_ber_sequence
-    write pkt
-
-    (be = read) &&
-    (pdu = Net::LDAP::PDU.new( be )) && (pdu.app_tag == Net::LDAP::PDU::ModifyRDNResponse) or
-    raise Net::LDAP::LdapError.new( "response missing or invalid" )
-
-    pdu
-  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"
-    controls = args.include?(:control_codes) ? args[:control_codes].to_ber_control : nil #use nil so we can compact later
-    request = dn.to_s.to_ber_application_string(10)
-    pkt = [next_msgid.to_ber, request, controls].compact.to_ber_sequence
-    write pkt
-
-    (be = read) && (pdu = Net::LDAP::PDU.new(be)) && (pdu.app_tag == Net::LDAP::PDU::DeleteResponse) or raise Net::LDAP::LdapError, "response missing or invalid"
-
-    pdu
-  end
-end # class Connection