DOCSP-41960 - TLS

snooty.toml

@@ -24,7 +24,9 @@ toc_landing_pages = [
 php-library = "MongoDB PHP Library"
 
 [constants]
+
 php-library = "MongoDB PHP Library"
 driver-short = "PHP library"
 mdb-server = "MongoDB Server"
-api = "https://www.mongodb.com/docs/php-library/current/reference"
+driver-short = "PHP library"
+api = "https://www.mongodb.com/docs/php-library/current/reference"

source/connect/tls.txt

@@ -0,0 +1,268 @@
+.. _php-tls:
+
+========================================
+Configure Transport Layer Security (TLS) 
+========================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: security, authentication, transport layer security, encrypt
+
+Overview
+--------
+
+In this guide, you can learn how to use the :wikipedia:`TLS <Transport_Layer_Security>`
+protocol to secure your connection to a MongoDB deployment.
+
+When you enable TLS for a connection, the {+driver-short+} performs the following actions:
+
+- Uses TLS to connect to the MongoDB deployment
+- Verifies the deployment's certificate
+- Ensures that the certificate certifies the deployment
+
+To learn how to configure your MongoDB deployment for TLS, see the
+:manual:`TLS configuration guide </tutorial/configure-ssl/>` in the
+{+mdb-server+} manual. 
+
+.. note::
+
+   This page assumes prior knowledge of TLS/SSL and access to valid certificates.
+   A full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and
+   Certificate Authorities (CAs) is beyond the scope of this documentation. 
+
+.. tip::
+
+   The {+driver-short+} delegates most TLS behavior to the MongoDB C Driver.
+   For information about how the C driver handles TLS, including configuration steps
+   and expected behavior, see
+   `Configuring TLS <https://www.mongodb.com/docs/languages/c/c-driver/current/libmongoc/guides/configuring_tls/#supported-libraries>`__
+   in the C driver Documentation.
+
+.. _php-enable-tls:
+
+Enable TLS
+----------
+
+To enable TLS for the connection to your MongoDB deployment, set the ``tls`` connection
+option to ``true``. You can do this in two ways: by using the ``uriOptions`` parameter
+of the ``MongoDB\Client`` constructor or through a parameter in your connection string.
+
+.. include:: /includes/connect/tls-tabs.rst
+
+.. tip::
+
+   If your connection string includes the ``+srv`` modification, which specifies the
+   SRV connection format, TLS is enabled on your connection by default.
+
+   To learn more about the SRV connection format, see
+   :manual:`SRV Connection Format </reference/connection-string/#srv-connection-format>`
+   in the {+mdb-server+} documentation.
+
+.. _php-specify-ca-file:
+
+Specify a CA File
+------------------
+
+During the TLS handshake, the MongoDB deployment presents a certificate key file to your
+application to establish its identity. Usually, a deployment's certificate has been
+signed by a well-known CA (certificate authority), and your application relies on this CA
+to validate the certificate.
+
+During testing, however, you might want to act as your own CA.
+In this case, you must instruct the {+driver-short+} to
+use your CA certificates instead of ones signed by another CA.
+
+To do so, use the ``tlsCAFile`` connection option to specify the path to a ``.pem`` file
+containing the root certificate chain.
+You can do this in two ways: by using the ``uriOptions`` parameter
+of the ``MongoDB\Client`` constructor or through a parameter in your connection string.
+
+.. include:: /includes/connect/ca-file-tabs.rst
+
+.. _php-specify-ca-directory:
+
+Specify a CA Directory
+~~~~~~~~~~~~~~~~~~~~~~
+
+If you are using OpenSSL or LibreSSL (``libtls``) for TLS support, you can also use
+the ``ca_dir`` option to instruct
+the {+driver-short+} to search for a CA file within a directory. The driver searches this
+directory if it doesn't find a CA file at the path specified in the ``tlsCAFile`` option.
+
+The following code example shows how to use the ``driverOptions`` parameter to specify the
+``ca_dir`` option:
+
+.. literalinclude:: /includes/connect/ca-dir.php
+      :language: php
+      :copyable: true
+
+.. tip:: 
+
+   This option corresponds to the OpenSSL
+   `SSL_CTX_load_verify_locations <https://linux.die.net/man/3/ssl_ctx_load_verify_locations>`__
+   parameter and
+   the LibreSSL `tls_config_set_ca_path <https://man.openbsd.org/tls_load_file.3>`__
+   parameter.
+
+.. _php-certificate-revocation:
+
+Check Certificate Revocation
+----------------------------
+
+When an X.509 certificate is no longer trustworthy—for example, if its private key
+has been compromised—the CA revokes the certificate. The {+driver-short+} includes two ways
+to check whether a server's certificate has been revoked.
+
+.. _php-disable-ocsp:
+
+OCSP
+~~~~
+
+The Online Certificate Status Protocol (OCSP) process varies depending on the version of
+{+mdb-server+} you're connecting to:
+
+- **MongoDB v4.4 or later:** The server staples a
+  time-stamped OCSP response to its certificate. The {+driver-short+} validates the certificate
+  against the OCSP response. If the CA has revoked the certificate, or if the OCSP response
+  is otherwise invalid, the TLS handshake fails.
+- **MongoDB v4.3 or earlier:** The server supplies an OCSP endpoint, which the {+driver-short+}
+  contacts directly. The {+driver-short+} then validates the certificate against the OCSP
+  response. If the CA hasn't revoked the certificate, the TLS handshake continues, even if
+  the OCSP response is invalid or malformed.
+
+To stop the {+driver-short+} from contacting the OCSP endpoint, set the
+``tlsDisableOCSPEndpointCheck`` connection option to ``true``.
+You can do this in two ways: by passing an argument to the
+``MongoDB\Client`` constructor or through a parameter in your connection string.
+
+.. include:: /includes/connect/ocsp-tabs.rst
+
+.. note::
+
+   Even if the ``tlsDisableOCSPEndpointCheck`` option is set to ``true``, the {+driver-short+}
+   still verifies any OCSP response stapled to a server's certificate.
+
+.. _php-crl:
+
+Certificate Revocation List
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Instead of using OCSP, you can use the instruct the {+driver-short+}
+to check the server's certificate
+against a Certificate Revocation List (CRL) published by the CA. To do so, set the
+``crl_file`` option to the file path of the CRL. Include this option in the
+``driverOptions`` parameter of the ``MongoDB\Client`` constructor, as shown
+in the following code example: 
+
+.. literalinclude:: /includes/connect/crl-file.php
+      :language: php
+      :copyable: true
+
+.. tip::
+
+   You can specify a CRL file in either the ``.pem`` or ``.der`` format.
+
+.. _php-client-cert:
+
+Present a Client Certificate
+----------------------------
+
+Some MongoDB deployments require every connecting application to present a client certificate
+that proves its identity. To specify the client certificate for the {+driver-short+} to
+present, set the ``tleCertificateKeyFile`` option to the file path of the ``.pem`` file that
+contains your certificate and private key.
+
+You can do this in two ways: by using the ``uriOptions`` parameter
+of the ``MongoDB\Client`` constructor or through a parameter in your connection string.
+
+.. include:: /includes/connect/client-cert-tabs.rst
+
+.. important::
+
+   Your client certificate and private key must be in the same ``.pem`` file. If they
+   are stored in different files, you must concatenate them. The following example
+   shows how to concatenate a key file and a certificate file into a third file called
+   ``combined.pem`` on a Unix system: 
+
+   .. code-block:: sh
+
+      $ cat key.pem cert.pem > combined.pem
+
+.. _php-key-file-password:
+
+Provide a Key Password
+~~~~~~~~~~~~~~~~~~~~~~
+
+If the private key in your certificate file is encrypted, you must use the
+``tlsCertificateKeyFilePassword`` option to provide the password.
+You can do this in two ways: by using the ``uriOptions`` parameter
+of the ``MongoDB\Client`` constructor or through a parameter in your connection string.
+
+.. include:: /includes/connect/key-file-password.rst
+
+.. _php-insecure-tls:
+
+Allow Insecure TLS
+------------------
+
+When TLS is enabled, the {+driver-short+} automatically verifies the certificate that
+the server presents. When testing your code, you can disable this verification.
+This is known as *insecure TLS.*
+
+When insecure TLS is enabled, the driver requires only that the server present an
+X.509 certificate. The driver accepts a certificate even if any of the following are
+true: 
+
+- The hostname of the server and the subject name (or subject alternative name) 
+  on the certificate don't match.
+- The certificate is expired or not yet valid. 
+- The certificate doesn't have a trusted root certificate in the chain. 
+- The certificate purpose isn't valid for server identification.
+
+.. note::
+
+   Even when insecure TLS is enabled, communication between the client and server
+   is encrypted with TLS.
+
+To enable insecure TLS, set the ``tlsInsecure`` connection
+option to ``true``. You can do this in two ways: by passing an argument to the
+``MongoDB\Client`` constructor or through a parameter in your connection string.
+
+.. include:: /includes/connect/insecure-tls-tabs.rst
+
+To disable only certificate validation, set the ``tlsAllowInvalidCertificates`` option to
+``true``, and set the ``tlsInsecure`` option to ``false`` or omit it:
+
+.. include:: /includes/connect/disable-cert-validation-tabs.rst
+
+To disable only hostname verification, set the ``tlsAllowInvalidHostnames`` option to
+``true``, and set the ``tlsInsecure`` option to ``false`` or omit it:
+
+.. include:: /includes/connect/disable-host-verification-tabs.rst
+
+.. warning:: Don't Use in Production
+
+   Always set the ``tlsInsecure``, ``tlsAllowInvalidCertificates``, and
+   ``tlsAllowInvalidHostnames`` options to ``false`` in production.
+
+   Setting any of these options to ``true`` in a production environment makes
+   your application insecure and potentially
+   vulnerable to expired certificates and to foreign processes posing
+   as valid client instances.
+
+API Documentation
+-----------------
+
+To learn more about configuring TLS for the {+driver-short+},
+see the following API documentation:
+
+- :ref:`MongoDB\Client <php-mongodb-client>`

source/includes/connect/ca-dir.php

@@ -0,0 +1,11 @@
+$uri = "mongodb://<hostname>:<port>";
+
+$uriOptions = [
+   'tls' => true,
+];
+
+$driverOptions = [
+    'ca_dir' => '/path/to/search/'
+];
+
+$client = new MongoDB\Client($uri, $uriOptions, $driverOptions);

source/includes/connect/ca-file-tabs.rst

@@ -0,0 +1,23 @@
+.. tabs::
+
+   .. tab:: MongoDB\\Client
+      :tabid: mongoclient
+
+      .. code-block:: php
+
+         $uri = "mongodb://<hostname>:<port>";
+
+         $options = [
+            'tls' => true,
+            'tlsCAFile' => '/path/to/ca.pem' 
+         ];
+
+         $client = new MongoDB\Client($uri, $options);
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: php
+
+         $uri = "mongodb://<hostname>:<port>/?tls=true&tlsCAFile=/path/to/ca.pem";
+         $client = MongoDB\Client($uri);

source/includes/connect/client-cert-tabs.rst

@@ -0,0 +1,23 @@
+.. tabs::
+
+   .. tab:: MongoDB\\Client
+      :tabid: mongoclient
+
+      .. code-block:: php
+
+         $uri = "mongodb://<hostname>:<port>";
+
+         $options = [
+            'tls' => true,
+            'tlsCertificateKeyFile' => '/path/to/client.pem' 
+         ];
+
+         $client = new MongoDB\Client($uri, $options);
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: php
+
+         $uri = "mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/client.pem";
+         $client = MongoDB\Client($uri);

source/includes/connect/crl-file.php

@@ -0,0 +1,11 @@
+$uri = "mongodb://<hostname>:<port>";
+
+$uriOptions = [
+   'tls' => true,
+];
+
+$driverOptions = [
+    'crl_file' => '/path/to/file.pem'
+];
+
+$client = new MongoDB\Client($uri, $uriOptions, $driverOptions);

source/includes/connect/crl-tabs.rst

@@ -0,0 +1,23 @@
+.. tabs::
+
+   .. tab:: MongoDB\\Client
+      :tabid: mongoclient
+
+      .. code-block:: php
+
+         $uri = "mongodb://<hostname>:<port>";
+
+         $options = [
+            'tls' => true,
+            'tlsCRLFile' => '/path/to/crl.pem' 
+         ];
+
+         $client = new MongoDB\Client($uri, $options);
+
+   .. tab:: Connection String
+      :tabid: connectionstring
+
+      .. code-block:: php
+
+         $uri = "mongodb://<hostname>:<port>/?tls=true&tlsCRLFile=/path/to/crl.pem";
+         $client = MongoDB\Client($uri);