diff --git a/snooty.toml b/snooty.toml index 28b89f14..e30bbbc3 100644 --- a/snooty.toml +++ b/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" \ No newline at end of file +driver-short = "PHP library" +api = "https://www.mongodb.com/docs/php-library/current/reference" diff --git a/source/connect/tls.txt b/source/connect/tls.txt new file mode 100644 index 00000000..f5e6fe23 --- /dev/null +++ b/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 ` +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 ` 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 `__ + 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 ` + 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 `__ + parameter and + the LibreSSL `tls_config_set_ca_path `__ + 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 ` \ No newline at end of file diff --git a/source/includes/connect/ca-dir.php b/source/includes/connect/ca-dir.php new file mode 100644 index 00000000..3618529b --- /dev/null +++ b/source/includes/connect/ca-dir.php @@ -0,0 +1,11 @@ +$uri = "mongodb://:"; + +$uriOptions = [ + 'tls' => true, +]; + +$driverOptions = [ + 'ca_dir' => '/path/to/search/' +]; + +$client = new MongoDB\Client($uri, $uriOptions, $driverOptions); diff --git a/source/includes/connect/ca-file-tabs.rst b/source/includes/connect/ca-file-tabs.rst new file mode 100644 index 00000000..b0b85bc8 --- /dev/null +++ b/source/includes/connect/ca-file-tabs.rst @@ -0,0 +1,23 @@ +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: mongoclient + + .. code-block:: php + + $uri = "mongodb://:"; + + $options = [ + 'tls' => true, + 'tlsCAFile' => '/path/to/ca.pem' + ]; + + $client = new MongoDB\Client($uri, $options); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = "mongodb://:/?tls=true&tlsCAFile=/path/to/ca.pem"; + $client = MongoDB\Client($uri); \ No newline at end of file diff --git a/source/includes/connect/client-cert-tabs.rst b/source/includes/connect/client-cert-tabs.rst new file mode 100644 index 00000000..961fc987 --- /dev/null +++ b/source/includes/connect/client-cert-tabs.rst @@ -0,0 +1,23 @@ +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: mongoclient + + .. code-block:: php + + $uri = "mongodb://:"; + + $options = [ + 'tls' => true, + 'tlsCertificateKeyFile' => '/path/to/client.pem' + ]; + + $client = new MongoDB\Client($uri, $options); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = "mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem"; + $client = MongoDB\Client($uri); \ No newline at end of file diff --git a/source/includes/connect/crl-file.php b/source/includes/connect/crl-file.php new file mode 100644 index 00000000..1a37b5e2 --- /dev/null +++ b/source/includes/connect/crl-file.php @@ -0,0 +1,11 @@ +$uri = "mongodb://:"; + +$uriOptions = [ + 'tls' => true, +]; + +$driverOptions = [ + 'crl_file' => '/path/to/file.pem' +]; + +$client = new MongoDB\Client($uri, $uriOptions, $driverOptions); diff --git a/source/includes/connect/crl-tabs.rst b/source/includes/connect/crl-tabs.rst new file mode 100644 index 00000000..f0a63f9d --- /dev/null +++ b/source/includes/connect/crl-tabs.rst @@ -0,0 +1,23 @@ +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: mongoclient + + .. code-block:: php + + $uri = "mongodb://:"; + + $options = [ + 'tls' => true, + 'tlsCRLFile' => '/path/to/crl.pem' + ]; + + $client = new MongoDB\Client($uri, $options); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = "mongodb://:/?tls=true&tlsCRLFile=/path/to/crl.pem"; + $client = MongoDB\Client($uri); \ No newline at end of file diff --git a/source/includes/connect/disable-cert-validation-tabs.rst b/source/includes/connect/disable-cert-validation-tabs.rst new file mode 100644 index 00000000..bcdc0e76 --- /dev/null +++ b/source/includes/connect/disable-cert-validation-tabs.rst @@ -0,0 +1,23 @@ +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: mongoclient + + .. code-block:: php + + $uri = "mongodb://:"; + + $options = [ + 'tls' => true, + 'tlsAllowInvalidCertificates' => true + ]; + + $client = new MongoDB\Client($uri, $options); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = "mongodb://:/?tls=true&tlsAllowInvalidCertificates=true"; + $client = MongoDB\Client($uri); \ No newline at end of file diff --git a/source/includes/connect/disable-host-verification-tabs.rst b/source/includes/connect/disable-host-verification-tabs.rst new file mode 100644 index 00000000..db4b8d1b --- /dev/null +++ b/source/includes/connect/disable-host-verification-tabs.rst @@ -0,0 +1,23 @@ +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: mongoclient + + .. code-block:: php + + $uri = "mongodb://:"; + + $options = [ + 'tls' => true, + 'tlsAllowInvalidHostnames' => true + ]; + + $client = new MongoDB\Client($uri, $options); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = "mongodb://:/?tls=true&tlsAllowInvalidHostnames=true"; + $client = MongoDB\Client($uri); \ No newline at end of file diff --git a/source/includes/connect/insecure-tls-tabs.rst b/source/includes/connect/insecure-tls-tabs.rst new file mode 100644 index 00000000..97600fbf --- /dev/null +++ b/source/includes/connect/insecure-tls-tabs.rst @@ -0,0 +1,23 @@ +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: mongoclient + + .. code-block:: php + + $uri = "mongodb://:"; + + $options = [ + 'tls' => true, + 'tlsInsecure' => true + ]; + + $client = new MongoDB\Client($uri, $options); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = "mongodb://:/?tls=true&tlsInsecure=true"; + $client = MongoDB\Client($uri); \ No newline at end of file diff --git a/source/includes/connect/key-file-password.rst b/source/includes/connect/key-file-password.rst new file mode 100644 index 00000000..2cb710c9 --- /dev/null +++ b/source/includes/connect/key-file-password.rst @@ -0,0 +1,24 @@ +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: mongoclient + + .. code-block:: php + + $uri = "mongodb://:"; + + $options = [ + 'tls' => true, + 'tlsCertificateKeyFile' => '/path/to/client.pem', + 'tlsCertificateKeyFilePassword' => '' + ]; + + $client = new MongoDB\Client($uri, $options); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = "mongodb://:/?tls=true&tlsCertificateKeyFile=/path/to/client.pem&tlsCertificateKeyFilePassword="; + $client = MongoDB\Client($uri); \ No newline at end of file diff --git a/source/includes/connect/ocsp-tabs.rst b/source/includes/connect/ocsp-tabs.rst new file mode 100644 index 00000000..1e393689 --- /dev/null +++ b/source/includes/connect/ocsp-tabs.rst @@ -0,0 +1,23 @@ +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: mongoclient + + .. code-block:: php + + $uri = "mongodb://:"; + + $options = [ + 'tls' => true, + 'tlsDisableOCSPEndpointCheck' => true + ]; + + $client = new MongoDB\Client($uri, $options); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = "mongodb://:/?tls=true&tlsDisableOCSPEndpointCheck=true"; + $client = MongoDB\Client($uri); \ No newline at end of file diff --git a/source/includes/connect/tls-tabs.rst b/source/includes/connect/tls-tabs.rst new file mode 100644 index 00000000..1bb80731 --- /dev/null +++ b/source/includes/connect/tls-tabs.rst @@ -0,0 +1,22 @@ +.. tabs:: + + .. tab:: MongoDB\\Client + :tabid: mongoclient + + .. code-block:: php + + $uri = "mongodb://:"; + + $options = [ + 'tls' => true + ]; + + $client = new MongoDB\Client($uri, $options); + + .. tab:: Connection String + :tabid: connectionstring + + .. code-block:: php + + $uri = "mongodb://:/?tls=true"; + $client = MongoDB\Client($uri); \ No newline at end of file