RUBY-2398 Use TLS instead of SSL in driver documentation (#2089)

* RUBY-2398 Use TLS instead of SSL in driver documentation

* change the docstrings also

* chase message change in tests

Co-authored-by: Oleg Pudeyev <[email protected]>

Author: p-mongo

source/installation.txt

@@ -33,21 +33,24 @@ of improvements and changes in each version of the driver.
 TLS/SSL and the Ruby Driver
 ===========================
 
-Industry best practices, and some regulations, require the use of TLS 1.1 or newer. Though no application changes are
-required for the Ruby driver to make use of the newest protocols, some operating systems or versions may not provide
-an OpenSSL version new enough to support them.
+Industry best practices, and some regulations, require the use of TLS 1.1
+or newer. Though no application changes are required for the Ruby driver to
+make use of the newest protocols, some operating systems or versions may
+not provide an OpenSSL version new enough to support them.
 
-Users of macOS older than 10.13 (High Sierra) will need to install Ruby from `rvm`_, `homebrew`_, `macports`_, or
-another similar source. See `installation information on ruby-lang.org`_ for more options.
+Users of macOS older than 10.13 (High Sierra) will need to install Ruby from
+`rvm`_, `homebrew`_, `macports`_, or another similar source. See
+`installation information on ruby-lang.org`_ for more options.
 
 Users of Linux or other non-macOS Unix can check their OpenSSL version like this:
 
 .. code-block:: sh
 
   $ openssl version
 
-If the version number is less than 1.0.1 support for TLS 1.1 or newer is not available. Contact your operating system
-vendor for a solution or upgrade to a newer distribution.
+If the version number is less than 1.0.1 support for TLS 1.1 or newer is
+not available. Contact your operating system vendor for a solution or upgrade
+to a newer distribution.
 
 You can check your Ruby interpreter by executing the following command:
 

source/reference/driver-compatibility.txt

@@ -462,7 +462,8 @@ Atlas Compatibility
 
 `Driver version 2.6.1 <https://github.com/mongodb/mongo-ruby-driver/releases/tag/v2.6.1>`_
 or higher is recommended when using MongoDB Atlas, as this version has
-significant SSL performance improvements.
+significant performance improvements when TLS connections are used, and all
+Atlas connections use TLS.
 
 When running on JRuby and connecting to Atlas Free Tier,
 `driver version 2.6.4 <https://github.com/mongodb/mongo-ruby-driver/releases/tag/v2.6.4>`_
@@ -487,8 +488,8 @@ the driver.
      - |checkmark|
 
 
-JRuby Kerberos
-==============
+JRuby and Kerberos Authentication
+=================================
 
 If the ``mongo_kerberos`` gem is used for Kerberos authentication with JRuby, the the JVM system
 property "sun.security.jgss.native" to will be set to "true" in order to facilitate the use of
@@ -498,3 +499,12 @@ obtaining Kerberos credentials as well.
 
 .. include:: /includes/unicode-checkmark.rst
 .. include:: /includes/unicode-nbsp.rst
+
+
+JRuby and TLS Connections
+=========================
+
+Due to JRuby limitations:
+
+- ECDSA server certificates are not supported.
+- OCSP endpoint checking is not performed.

source/tutorials/ruby-driver-authentication.txt

@@ -191,14 +191,14 @@ value for the ``authMechanism`` URI option, as follows:
 Client Certificate (X.509)
 ``````````````````````````
 
-The driver presents an X.509 certificate during SSL negotiation.
+The driver presents an X.509 certificate during TLS negotiation.
 The MONGODB-X509 authentication mechanism authenticates a username
 derived from the distinguished subject name of this certificate.
 
-This authentication method requires the use of SSL connections with
+This authentication method requires the use of TLS connections with
 certificate validation.
 
-To authenticate the client, you will need a valid SSL certificate
+To authenticate the client, you will need a valid TLS certificate
 and private encryption key. These can be stored in separate files,
 or together in one file (in the PEM format). Even if the certificate
 and private key are stored in the same file, you must specify the path to
@@ -393,7 +393,7 @@ Access Protocol `LDAP <http://en.wikipedia.org/wiki/LDAP>`_ server.
 .. warning::
 
   When using LDAP, passwords are sent to the server in plain text. For this
-  reason, we strongly recommend enabling SSL when using LDAP as your
+  reason, we strongly recommend enabling TLS when using LDAP as your
   authentication mechanism.
 
 For more information about configuring LDAP authentication in

source/tutorials/ruby-driver-create-client.txt

@@ -496,27 +496,30 @@ Ruby Options
      - none
 
    * - ``:ssl``
-     - Tell the client to connect to the servers via SSL.
+     - Tell the client to connect to the servers via TLS.
      - ``Boolean``
      - false
 
    * - ``:ssl_ca_cert``
-     - The file path containing concatenated certificate authority certificates used to validate certs
-       passed from the other end of the connection. One of :ssl_ca_cert, :ssl_ca_cert_string or :ssl_ca_cert_object
+     - The file path containing concatenated certificate authority certificates
+       used to validate certs passed from the other end of the connection.
+       One of :ssl_ca_cert, :ssl_ca_cert_string or :ssl_ca_cert_object
        (in order of priority) is required for :ssl_verify.
      - ``String``
      - none
 
    * - ``:ssl_ca_cert_object``
-     - An array of OpenSSL::X509::Certificate representing the certificate authority certificates used to
-       validate certs passed from the other end of the connection. One of :ssl_ca_cert, :ssl_ca_cert_string or
+     - An array of OpenSSL::X509::Certificate representing the certificate
+       authority certificates used to validate certs passed from the other end
+       of the connection. One of :ssl_ca_cert, :ssl_ca_cert_string or
        :ssl_ca_cert_object (in order of priority) is required for :ssl_verify.
      - ``Array< OpenSSL::X509::Certificate >``
      - none
 
    * - ``:ssl_ca_cert_string``
-     - A string containing concatenated certificate authority certificates used to validate certs
-       passed from the other end of the connection. One of :ssl_ca_cert, :ssl_ca_cert_string or :ssl_ca_cert_object
+     - A string containing concatenated certificate authority certificates
+       used to validate certs passed from the other end of the connection.
+       One of :ssl_ca_cert, :ssl_ca_cert_string or :ssl_ca_cert_object
        (in order of priority) is required for :ssl_verify.
      - ``String``
      - none
@@ -578,8 +581,9 @@ Ruby Options
      - none
 
    * - ``:ssl_key_string``
-     - A string containing the PEM-encoded private key used to identify the connection against MongoDB.
-       This parameter, if present, takes precedence over the value of option :ssl_key_object.
+     - A string containing the PEM-encoded private key used to identify the
+       connection against MongoDB. This parameter, if present, takes precedence
+       over the value of option :ssl_key_object.
      - ``String``
      - none
 
@@ -594,14 +598,16 @@ Ruby Options
      - true
 
    * - ``:ssl_verify_certificate``
-     - Whether to perform peer certificate validation. This setting overrides :ssl_verify with
-       respect to whether certificate validation is performed.
+     - Whether to perform peer certificate validation. This setting overrides
+       the ``:ssl_verify`` setting with respect to whether certificate
+       validation is performed.
      - ``Boolean``
      - true
 
    * - ``:ssl_verify_hostname``
      - Whether to perform peer hostname validation. This setting overrides
-      :ssl_verify with respect to whether hostname validation is performed.
+       the ``:ssl_verify`` setting with respect to whether hostname validation
+       is performed.
      - ``Boolean``
      - true
 
@@ -811,18 +817,18 @@ URI options are explained in detail in the :manual:`Connection URI reference
    * - tlsAllowInvalidCertificates=Boolean
      - ``:ssl_verify_certificate => boolean``
 
-       Because ``tlsAllowInvalidCertificates`` uses ``true`` to signify that verification
-       should be disabled and ``ssl_verify_certificate`` uses ``false`` to signify that
-       verification should be disabled, the boolean is inverted before being used to set
-       ``ssl_verify_certificate``.
+       Because ``tlsAllowInvalidCertificates`` uses ``true`` to signify that
+       verification should be disabled and ``ssl_verify_certificate`` uses
+       ``false`` to signify that verification should be disabled, the boolean
+       is inverted before being used to set ``ssl_verify_certificate``.
 
    * - tlsAllowInvalidHostnames=Boolean
      - ``:ssl_verify_hostname => boolean``
 
-       Because ``tlsAllowInvalidHostnames`` uses ``true`` to signify that verification
-       should be disabled and ``ssl_verify_hostname`` uses ``false`` to signify that
-       verification should be disabled, the boolean is inverted before being used to set
-       ``ssl_verify_hostname``.
+       Because ``tlsAllowInvalidHostnames`` uses ``true`` to signify that
+       verification should be disabled and ``ssl_verify_hostname`` uses
+       ``false`` to signify that verification should be disabled, the boolean
+       is inverted before being used to set ``ssl_verify_hostname``.
 
    * - tlsCAFile=String
      - ``:ssl_ca_cert => String``
@@ -847,9 +853,10 @@ URI options are explained in detail in the :manual:`Connection URI reference
    * - tlsInsecure=Boolean
      - ``:ssl_verify => boolean``
 
-       Because tlsInsecure uses ``true`` to signify that verification should be disabled and
-       ``ssl_verify`` uses ``false`` to signify that verification should be disabled, the boolean
-       is inverted before being used to set ``ssl_verify``.
+       Because tlsInsecure uses ``true`` to signify that verification should
+       be disabled and ``ssl_verify`` uses ``false`` to signify that
+       verification should be disabled, the boolean is inverted before being
+       used to set ``ssl_verify``.
 
    * - w=Integer|String
      - ``{ :write_concern => { :w => Integer|String }}``
@@ -987,6 +994,20 @@ To connect to the MongoDB deployment using TLS:
 
   When using JRuby, ECDSA certificates are not currently supported.
 
+TLS vs SSL Option Names
+-----------------------
+
+All MongoDB server versions supported by the Ruby driver (2.6 and higher)
+only implement TLS. 2.6 and higher servers do not use SSL.
+
+For historical reasons, the Ruby option names pertaining to TLS configuration
+use the ``ssl`` rather than the ``tls`` prefix. The next major version of
+the Ruby driver (3.0) will use the ``tls`` prefix for Ruby option names.
+
+The URI option names use the ``tls`` prefix, with one exception: there is
+a ``ssl`` URI option that is deprecated and equivalent to the ``tls`` URI
+option.
+
 Enable TLS Connections
 ----------------------