clean up TLS docs

- rename SSL to TLS where appropriate
- consolidate TLS documentation into one guide, linked to from
"Advanced Connections", mongoc_ssl_opt_t, and URI options
- fix incorrectly documented tlscertificateauthorityfile URI
option

Author: kevinAlbs

src/libmongoc/doc/advanced-connections.rst

@@ -109,7 +109,8 @@ Include username and password like so:
 
   mongoc_uri_t *uri = mongoc_uri_new ("mongodb://user:pass@%2Ftmp%2Fmongodb-27017.sock");
 
-Connecting to a server over SSL
+
+Connecting to a server over TLS
 -------------------------------
 
 These are instructions for configuring TLS/SSL connections.
@@ -118,33 +119,28 @@ To run a server locally (on port 27017, for example):
 
 .. code-block:: none
 
-  $ mongod --port 27017 --sslMode requireSSL --sslPEMKeyFile server.pem --sslCAFile ca.pem
+  $ mongod --port 27017 --tlsMode requireTLS --tlsCertificateKeyFile server.pem --tlsCAFile ca.pem
 
-Add ``/?ssl=true`` to the end of a client URI.
+Add ``/?tls=true`` to the end of a client URI.
 
 .. code-block:: none
 
   mongoc_client_t *client = NULL;
-  client = mongoc_client_new ("mongodb://localhost:27017/?ssl=true");
+  client = mongoc_client_new ("mongodb://localhost:27017/?tls=true");
 
-MongoDB requires client certificates by default, unless the ``--sslAllowConnectionsWithoutCertificates`` is provided. The C Driver can be configured to present a client certificate using a ``mongoc_ssl_opt_t``:
+MongoDB requires client certificates by default, unless the ``--tlsAllowConnectionsWithoutCertificates`` is provided. The C Driver can be configured to present a client certificate using the URI option ``tlsCertificateKeyFile``, which may be referenced through the constant ``MONGOC_URI_TLSCERTIFICATEKEYFILE``.
 
 .. code-block:: none
 
-  const mongoc_ssl_opt_t *ssl_default = mongoc_ssl_opt_get_default ();
-  mongoc_ssl_opt_t ssl_opts = { 0 };
-
-  /* optionally copy in a custom trust directory or file; otherwise the default is used. */
-  memcpy (&ssl_opts, ssl_default, sizeof ssl_opts);
-  ssl_opts.pem_file = "client.pem"
-
-  mongoc_client_set_ssl_opts (client, &ssl_opts);
+  mongoc_client_t *client = NULL;
+  mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017/?tls=true");
+  mongoc_uri_set_option_as_utf8 (uri, MONGOC_URI_TLSCERTIFICATEKEYFILE, "client.pem");
 
-The client certificate provided by ``pem_file`` must be issued by one of the server trusted Certificate Authorities listed in ``--sslCAFile``, or issued by a CA in the native certificate store on the server when omitted.
+  client = mongoc_client_new_from_uri (uri);
 
-To verify the server certificate against a specific CA, provide a PEM armored file with a CA certificate, or concatenated list of CA certificates using the ``ca_file`` option, or ``c_rehash`` directory structure of CAs, pointed to using the ``ca_dir`` option. When no ``ca_file`` or ``ca_dir`` is provided, the driver will use CAs provided by the native platform certificate store.
+The client certificate provided by ``tlsCertificateKeyFile`` must be issued by one of the server trusted Certificate Authorities listed in ``--tlsCAFile``, or issued by a CA in the native certificate store on the server when omitted.
 
-See :doc:`mongoc_ssl_opt_t` for more information on the various SSL related options.
+See :doc:`configuring_tls` for more information on the various TLS related options.
 
 Compressing data to and from MongoDB
 ------------------------------------

src/libmongoc/doc/authentication.rst

@@ -155,7 +155,7 @@ MongoDB Enterprise Edition supports the ``SASL PLAIN`` authentication mechanism,
 
 .. note::
 
-  ``SASL PLAIN`` is a clear-text authentication mechanism. It is strongly recommended to connect to MongoDB using SSL with certificate validation when using the ``PLAIN`` mechanism.
+  ``SASL PLAIN`` is a clear-text authentication mechanism. It is strongly recommended to connect to MongoDB using TLS with certificate validation when using the ``PLAIN`` mechanism.
 
 .. code-block:: none
 
@@ -172,13 +172,13 @@ X.509 Certificate Authentication
 
 .. note::
 
-  The MongoDB C Driver must be compiled with SSL support for X.509 authentication support. Once this is done, start a server with the following options:
+  The MongoDB C Driver must be compiled with TLS support for X.509 authentication support. Once this is done, start a server with the following options:
 
   .. code-block:: none
 
-    $ mongod --sslMode requireSSL --sslPEMKeyFile server.pem --sslCAFile ca.pem
+    $ mongod --tlsMode requireTLS --tlsCertificateKeyFile server.pem --tlsCAFile ca.pem
 
-The ``MONGODB-X509`` mechanism authenticates a username derived from the distinguished subject name of the X.509 certificate presented by the driver during SSL negotiation. This authentication method requires the use of SSL connections with certificate validation.
+The ``MONGODB-X509`` mechanism authenticates a username derived from the distinguished subject name of the X.509 certificate presented by the driver during TLS negotiation. This authentication method requires the use of TLS connections with certificate validation.
 
 .. code-block:: none
 

src/libmongoc/doc/conf.py

@@ -49,6 +49,7 @@
     '**': ['globaltoc.html', 'customindexlink.html', 'searchbox.html'],
     'errors': [],  # Make more room for the big table.
     'mongoc_uri_t': [],  # Make more room for the big table.
+    'configuring_tls': [],  # Make more room for the big table.
 }
 
 

src/libmongoc/doc/configuring_tls.rst

@@ -0,0 +1,114 @@
+:man_page: configuring_tls
+
+Configuring TLS
+===============
+
+Building libmongoc with TLS support
+-----------------------------------
+
+By default, libmongoc will attempt to find a supported TLS library and enable TLS support. This is controlled by the cmake flag ``ENABLE_SSL``, which is set to ``AUTO`` by default. Valid values are:
+
+- ``AUTO`` the default behavior. Link to the system's native TLS library, or attempt to find OpenSSL.
+- ``DARWIN`` link to Secure Transport, the native TLS library on macOS.
+- ``WINDOWS`` link to Secure Channel, the native TLS on Windows.
+- ``OPENSSL`` link to OpenSSL (libssl). An optional install path may be specified with ``OPENSSL_ROOT``.
+- ``LIBRESSL`` link to LibreSSL's libtls. (LibreSSL's compatible libssl may be linked to by setting ``OPENSSL``).
+- ``OFF`` disable TLS support.
+
+Configuration with URI options
+------------------------------
+
+Enable TLS by including ``tls=true`` the URI.
+
+.. code:: c
+   
+  mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017/");
+  mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
+
+  mongoc_client_t *client = mongoc_client_new_from_uri (uri);
+
+
+The following URI options may be used to further configure TLS:
+
+.. include:: includes/tls-options.txt
+
+Configuration with mongoc_ssl_opt_t
+-----------------------------------
+
+Alternatively, the :symbol:`mongoc_ssl_opt_t` struct may be used to configure TLS with :symbol:`mongoc_client_set_ssl_opts()` or :symbol:`mongoc_client_pool_set_ssl_opts()`. Most of the configurable options can be using the Connection URI.
+
+===============================  ===============================
+**mongoc_ssl_opt_t key**         **URI key**
+===============================  ===============================
+pem_file                         tlsClientCertificateKeyFile
+pem_pwd                          tlsClientCertificateKeyPassword
+ca_file                          tlsCAFile
+weak_cert_validation             tlsAllowInvalidCertificates
+allow_invalid_hostname           tlsAllowInvalidHostnames
+===============================  ===============================
+
+The only exclusions are ``crl_file`` and ``ca_dir``. Those may only be set with :symbol:`mongoc_ssl_opt_t`.
+
+Client Authentication
+---------------------
+
+When MongoDB is started with TLS enabled, it will by default require the client to provide a client certificate issued by a certificate authority specified by ``--tlsCAFile``, or an authority trusted by the native certificate store in use on the server.
+
+To provide the client certificate, set the ``tlscertificatekeyfile`` in the URI to a PEM armored certificate file.
+
+.. code-block:: c
+
+  mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017/");
+  mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
+  mongoc_uri_set_option_as_utf8 (uri, MONGOC_URI_TLSCERTIFICATEKEYFILE, "/path/to/client-certificate.pem");
+
+  mongoc_client_t *client = mongoc_client_new_from_uri (uri);
+
+Server Certificate Verification
+-------------------------------
+
+The MongoDB C Driver will automatically verify the validity of the server certificate, such as issued by configured Certificate Authority, hostname validation, and expiration.
+
+To overwrite this behaviour, it is possible to disable hostname validation, and/or allow otherwise invalid certificates. This behaviour is controlled using the ``tlsallowinvalidhostnames`` and ``tlsallowinvalidcertificates`` options. By default, both are set to ``false``. It is not recommended to change these defaults as it exposes the client to *Man In The Middle* attacks (when ``tlsallowinvalidhostnames`` is set) and otherwise invalid certificates when ``tlsallowinvalidcertificates`` is set to ``true``.
+
+OpenSSL
+-------
+
+The MongoDB C Driver uses OpenSSL, if available, on Linux and Unix platforms (besides macOS). Industry best practices and some regulations require the use of TLS 1.1 or newer, which requires at least OpenSSL 1.0.1. Check your OpenSSL version like so::
+
+  $ openssl version
+
+Ensure your system's OpenSSL is a recent version (at least 1.0.1), or install a recent version in a non-system path and build against it with::
+
+  cmake -DOPENSSL_ROOT_DIR=/absolute/path/to/openssl
+
+When compiled against OpenSSL, the driver will attempt to load the system default certificate store, as configured by the distribution. That can be overridden by setting the ``tlscafile`` URI option or with the fields ``ca_file`` and ``ca_dir`` in the :symbol:`mongoc_ssl_opt_t`.
+
+LibreSSL / libtls
+-----------------
+
+The MongoDB C Driver supports LibreSSL through the use of OpenSSL compatibility checks when configured to compile against ``openssl``. It also supports the new ``libtls`` library when configured to build against ``libressl``.
+
+Native TLS Support on Windows (Secure Channel)
+----------------------------------------------
+
+The MongoDB C Driver supports the Windows native TLS library (Secure Channel, or SChannel), and its native crypto library (Cryptography API: Next Generation, or CNG).
+
+When compiled against the Windows native libraries, the ``ca_dir`` option of a :symbol:`mongoc_ssl_opt_t` is not supported, and will issue an error if used.
+
+Encrypted PEM files (e.g., setting ``tlscertificatekeypassword``) are also not supported, and will result in error when attempting to load them.
+
+When ``tlscafile`` is set, the driver will only allow server certificates issued by the authority (or authorities) provided. When no ``tlscafile`` is set, the driver will look up the Certificate Authority using the ``System Local Machine Root`` certificate store to confirm the provided certificate or the ``Current user certificate store`` if the ``System Local Machine Root`` certificate store is unavailable.
+
+When ``crl_file`` is set with :symbol:`mongoc_ssl_opt_t`, the driver will import the revocation list to the ``System Local Machine Root`` certificate store.
+
+.. _Secure Transport:
+
+Native TLS Support on macOS / Darwin (Secure Transport)
+-------------------------------------------------------
+
+The MongoDB C Driver supports the Darwin (OS X, macOS, iOS, etc.) native TLS library (Secure Transport), and its native crypto library (Common Crypto, or CC).
+
+When compiled against Secure Transport, the ``ca_dir`` option of a :symbol:`mongoc_ssl_opt_t` is not supported, and will issue an error if used.
+
+When ``tlscafile`` is set, the driver will only allow server certificates issued by the authority (or authorities) provided. When no ``tlscafile`` is set, the driver will use the Certificate Authorities in the currently unlocked keychains.

src/libmongoc/doc/errors.rst

@@ -19,7 +19,7 @@ See also: :doc:`Handling Errors in libbson <bson:errors>`.
 +-----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 |                                         | ``MONGOC_ERROR_CLIENT_AUTHENTICATE``                                                                                            | Wrong credentials, or failure sending or receiving authentication messages.                                                                                                                                                                                                                                                                |
 +-----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-|                                         | ``MONGOC_ERROR_CLIENT_NO_ACCEPTABLE_PEER``                                                                                      | You tried an SSL connection but the driver was not built with SSL.                                                                                                                                                                                                                                                                         |
+|                                         | ``MONGOC_ERROR_CLIENT_NO_ACCEPTABLE_PEER``                                                                                      | You tried an TLS connection but the driver was not built with TLS.                                                                                                                                                                                                                                                                         |
 +-----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 |                                         | ``MONGOC_ERROR_CLIENT_IN_EXHAUST``                                                                                              | You began iterating an exhaust cursor, then tried to begin another operation with the same :symbol:`mongoc_client_t`.                                                                                                                                                                                                                      |
 +-----------------------------------------+---------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

src/libmongoc/doc/guides.rst

@@ -7,6 +7,7 @@ Guides
    :titlesonly:
    :maxdepth: 1
 
+   configuring_tls
    mongoc-common-task-examples
    advanced-connections
    connection-pooling

src/libmongoc/doc/includes/tls-options.txt

@@ -0,0 +1,27 @@
+.. list-table::
+   :header-rows:  1
+
+   * - Constant
+     - Key
+     - Description
+   * - MONGOC_URI_TLS
+     - tls
+     - {true|false}, indicating if TLS must be used.
+   * - MONGOC_URI_TLSCERTIFICATEKEYFILE
+     - tlscertificatekeyfile
+     - Path to PEM formatted Private Key, with its Public Certificate concatenated at the end.
+   * - MONGOC_URI_TLSCERTIFICATEKEYPASSWORD
+     - tlscertificatekeypassword
+     - The password, if any, to use to unlock encrypted Private Key.
+   * - MONGOC_URI_TLSCAFILE
+     - tlscafile
+     - One, or a bundle of, Certificate Authorities whom should be considered to be trusted.
+   * - MONGOC_URI_TLSALLOWINVALIDCERTIFICATES
+     - tlsallowinvalidcertificates
+     - Accept and ignore certificate verification errors (e.g. untrusted issuer, expired, etc.)
+   * - MONGOC_URI_TLSALLOWINVALIDHOSTNAMES
+     - tlsallowinvalidhostnames
+     - Ignore hostname verification of the certificate (e.g. Man In The Middle, using valid certificate, but issued for another hostname)
+   * - MONGOC_URI_TLSINSECURE
+     - tlsinsecure
+     - {true|false}, indicating if insecure TLS options should be used. Currently this implies MONGOC_URI_TLSALLOWINVALIDCERTIFICATES and MONGOC_URI_TLSALLOWINVALIDHOSTNAMES.

src/libmongoc/doc/installing.rst

@@ -78,7 +78,7 @@ Building on Unix
 Prerequisites for libmongoc
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-OpenSSL is required for authentication or for SSL connections to MongoDB. Kerberos or LDAP support requires Cyrus SASL.
+OpenSSL is required for authentication or for TLS connections to MongoDB. Kerberos or LDAP support requires Cyrus SASL.
 
 To install all optional dependencies on RedHat / Fedora:
 

src/libmongoc/doc/mongoc_client_pool_set_ssl_opts.rst

@@ -24,7 +24,7 @@ it points to (``pem_file``, ``pem_pwd``, ``ca_file``, ``ca_dir``, and
 ``crl_file``) so they don't have to remain valid after the call to
 ``mongoc_client_pool_set_ssl_opts``.
 
-A call to ``mongoc_client_pool_set_ssl_opts`` overrides all SSL options set
+A call to ``mongoc_client_pool_set_ssl_opts`` overrides all TLS options set
 through the connection string with which the ``mongoc_client_pool_t`` was
 constructed.
 

src/libmongoc/doc/mongoc_client_set_ssl_opts.rst

@@ -14,14 +14,14 @@ Synopsis
                               const mongoc_ssl_opt_t *opts);
   #endif
 
-Sets the SSL options to use when connecting to SSL enabled MongoDB servers.
+Sets the TLS (SSL) options to use when connecting to TLS enabled MongoDB servers.
 
 The ``mongoc_ssl_opt_t`` struct is copied by the client along with the strings
 it points to (``pem_file``, ``pem_pwd``, ``ca_file``, ``ca_dir``, and
 ``crl_file``) so they don't have to remain valid after the call to
 ``mongoc_client_set_ssl_opts``.
 
-A call to ``mongoc_client_set_ssl_opts`` overrides all SSL options set through
+A call to ``mongoc_client_set_ssl_opts`` overrides all TLS options set through
 the connection string with which the ``mongoc_client_t`` was constructed.
 
 It is a programming error to call this function on a client from a