add docs on how to actually validate an LDAP server cert

lib/net/ldap.rb

@@ -476,61 +476,73 @@ def self.result2string(code) #:nodoc:
   #   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 must be a Hash containing additional
   #   parameters, which consists of two keys:
   #     method: - :simple_tls or :start_tls
-  #     options: - Hash of options for that method
+  #     tls_options: - Hash of options for that method
   #   The :simple_tls encryption method encrypts <i>all</i> communications
   #   with the LDAP server. It completely establishes SSL/TLS encryption with
   #   the LDAP server before any LDAP-protocol data is exchanged. There is no
   #   plaintext negotiation and no special encryption-request controls are
   #   sent to the server. <i>The :simple_tls option is the simplest, easiest
   #   way to encrypt communications between Net::LDAP and LDAP servers.</i>
-  #   It's intended for cases where you have an implicit level of trust in the
-  #   authenticity of the LDAP server. No validation of the LDAP server's SSL
-  #   certificate is performed. This means that :simple_tls will not produce
-  #   errors if the LDAP server's encryption certificate is not signed by a
-  #   well-known Certification Authority. If you get communications or
-  #   protocol errors when using this option, check with your LDAP server
-  #   administrator. Pay particular attention to the TCP port you are
-  #   connecting to. It's impossible for an LDAP server to support plaintext
-  #   LDAP communications and <i>simple TLS</i> connections on the same port.
-  #   The standard TCP port for unencrypted LDAP connections is 389, but the
-  #   standard port for simple-TLS encrypted connections is 636. Be sure you
-  #   are using the correct port.
-  #
+  #   If you get communications or protocol errors when using this option,
+  #   check with your LDAP server administrator. Pay particular attention
+  #   to the TCP port you are connecting to. It's impossible for an LDAP
+  #   server to support plaintext LDAP communications and <i>simple TLS</i>
+  #   connections on the same port. The standard TCP port for unencrypted
+  #   LDAP connections is 389, but the standard port for simple-TLS
+  #   encrypted connections is 636. Be sure you are using the correct port.
   #   The :start_tls like the :simple_tls encryption method also encrypts all
   #   communcations with the LDAP server. With the exception that it operates
   #   over the standard TCP port.
   #
-  #   In order to verify certificates and enable other TLS options, the
-  #   :tls_options hash can be passed alongside :simple_tls or :start_tls.
-  #   This hash contains any options that can be passed to
-  #   OpenSSL::SSL::SSLContext#set_params(). The most common options passed
-  #   should be OpenSSL::SSL::SSLContext::DEFAULT_PARAMS, or the :ca_file option,
-  #   which contains a path to a Certificate Authority file (PEM-encoded).
-  #
-  #   Example for a default setup without custom settings:
-  #     {
-  #       :method => :simple_tls,
-  #       :tls_options => OpenSSL::SSL::SSLContext::DEFAULT_PARAMS
-  #     }
+  #   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...
   #
-  #   Example for specifying a CA-File and only allowing TLSv1.1 connections:
-  #
-  #     {
-  #       :method => :start_tls,
-  #       :tls_options => { :ca_file => "/etc/cafile.pem", :ssl_version => "TLSv1_1" }
+  #   Net::LDAP.new(
+  #     # ... set host, bind dn, etc ...
+  #     encryption: {
+  #       method: :simple_tls,
+  #       tls_options: { OpenSSL::SSL::SSLContext::DEFAULT_PARAMS },
   #     }
-  # * :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.
+  #   )
+  #
+  #   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