From ede66c1a50130f08bca112e4a1f7e74a8c1ae8e2 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 15 Jan 2025 13:30:51 -0500 Subject: [PATCH 01/14] Configure TLS --- source/connect.txt | 4 +- source/connect/tls.txt | 173 +++++++++++++++++++++++++++++++++ source/includes/connect/tls.rb | 30 ++++++ 3 files changed, 206 insertions(+), 1 deletion(-) create mode 100644 source/connect/tls.txt create mode 100644 source/includes/connect/tls.rb diff --git a/source/connect.txt b/source/connect.txt index f3b875c7..65a2c3ff 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -23,4 +23,6 @@ Connect to MongoDB :maxdepth: 1 /connect/mongoclient - /connect/stable-api \ No newline at end of file + /connect/stable-api + /connect/tls + \ No newline at end of file diff --git a/source/connect/tls.txt b/source/connect/tls.txt new file mode 100644 index 00000000..a7650e58 --- /dev/null +++ b/source/connect/tls.txt @@ -0,0 +1,173 @@ +.. _ruby-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 Transport Layer Security (TLS) +protocol to secure your connection to a MongoDB deployment. + +To connect to a MongoDB deployment using TLS, you must: + +- Enable TLS connections in ``Mongo::Client``. +- Specify the client TLS certificate. +- Specify the CA certificate to verify the server's TLS certificate. + +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. To + learn more about TLS, see the Wikipedia entry for :wikipedia:`Transport Layer Security `. + +.. _ruby-enable-tls: + +Enable TLS +---------- + +You can enable TLS for the connection to your MongoDB deployment in the following ways: + +- Set the ``ssl`` option to ``true`` in a new ``Mongo:Client`` object +- Set the ``tls`` option to ``true`` in your connection string + +.. note:: The {+driver-long+} does not support SSL + + All {+mdb-server+} versions supported by the Ruby driver (2.6 and higher) + only implement TLS. 2.6 and 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. + +.. tabs:: + + .. tab:: Mongo::Client + :tabid: mongoclient + + You must specify the following options for certificate paths: + + - ``ssl_cert``: The certificate file used to identify the connection against MongoDB. + - ``ssl_key``: The private keyfile used to identify the connection against MongoDB. + - ``ssl_ca_cert``: The file containing the concatenated certificate authority (CA) + certificates used to validate certs passed from the other end of the connection. + By default, the driver will use the default system root certificate + store as the trust anchor, if the option is not designated. + + These certificate options can be specified as different types. For example, the + ``ssl_cert`` option has the alternative ``ssl_cert_object`` and ``ssl_cert_string`` + options to specify the certificate file as either a certificate object or a string. + For more information on certificate options, see Options Hash section of + the API Documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__. + + In the following example, the TLS certificate and corresponding private key + are provided in separate files: + + .. literalinclude:: /includes/connect/tls.rb + :language: ruby + :dedent: + :start-after: start-enable-tls-settings + :end-before: end-enable-tls-settings + + The TLS certificate and private key can also be contained in the same file, but + both the certificate and private key options must still be specified. In the + following example, the TLS certificate and the private key are both defined + in the same ``client.pem`` file: + + .. literalinclude:: /includes/connect/tls.rb + :language: ruby + :dedent: + :start-after: start-enable-tls-settings-same-file + :end-before: end-enable-tls-settings-same-file + + .. tab:: Connection String + :tabid: uri + + You must specify the following URI options: + + - ``tlsCertificateKeyFile``: The certificate and key file used to identify + identify the connection against MongoDB. Both the certificate and key + must be stored in the same file provided to this option. + - ``tlsCAFile``: The file containing the concatenated certificate authority (CA) + certificates used to validate certificates passed from the other end of the + connection. The driver will use the default system root certificate + store as the trust anchor, if the option is not designated. + + .. literalinclude:: /includes/connect/tls.rb + :language: ruby + :dedent: + :start-after: start-enable-tls-uri + :end-before: end-enable-tls-uri + + The file containing the certificate and key usually has a``.crt`` or ``.pem`` + extension. + + URI option values must be properly URI escaped. This applies, for example, + to slashes (/) in the paths, which are encoded as ``%2f``. + +Modify the SSL Context +---------------------- + +If your TLS configuration requires customization, you can set TLS context hooks +by adding a native Ruby class ``Proc`` object to the ``Mongo.tls_context_hooks`` +array. The ``Proc`` should be added to the array before creating any ``Mongo::Client`` +instances. + +For example, the following code could be placed in an initializer to enable the +AES256-SHA cipher as the only cipher to be used for TLS: + +.. literalinclude:: /includes/connect/tls.rb + :language: ruby + :dedent: + :start-after: start-modify-context + :end-before: end-modify-context + +To learn more about the SSL context options available, see the Ruby +documentation for +`SSLContext `__. + +OCSP Verification +----------------- + +If the certificate provided by the server contains an OCSP endpoint URI, +the driver will issue an OCSP request to the specified endpoint to verify the +validity of the certificate by default. + +The OCSP endpoint check may be disabled by setting the +``:ssl_verify_ocsp_endpoint`` Ruby option to ``false`` or by setting the +``tlsDisableOCSPEndpointCheck`` URI option to ``true`` when creating a client. + +.. note:: + + OCSP endpoint checking is not currently performed when running on JRuby, + since JRuby does not correctly expose the OCSP endpoint URI. + +.. _ruby-tls-api: + +API Documentation +----------------- + +For more information about any of the types and methods discussed in this guide, +see the following API documentation: + +- `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ +- `tls_context_hooks <{+api-root+/Mongo.html#tls_context_hooks-class_method}>`__ diff --git a/source/includes/connect/tls.rb b/source/includes/connect/tls.rb new file mode 100644 index 00000000..eb3b22e5 --- /dev/null +++ b/source/includes/connect/tls.rb @@ -0,0 +1,30 @@ +# start-enable-tls-settings +client = Mongo::Client.new(["localhost:27017"], + ssl: true, + ssl_cert: 'path/to/client.crt', + ssl_key: 'path/to/client.key', + ssl_ca_cert: 'path/to/ca.crt', +) +# end-enable-tls-settings + +# start-enable-tls-settings-same-file +client = Mongo::Client.new(["localhost:27017"], + ssl: true, + ssl_cert: 'path/to/client.pem', + ssl_key: 'path/to/client.pem', + ssl_ca_cert: 'path/to/ca.crt', +) +# end-enable-tls-settings-same-file + +# start-enable-tls-uri +client = Mongo::Client.new( + "mongodb://localhost:27017/?tls=true&tlsCertificateKeyFile=path%2fto%2fclient.pem&tlsCAFile=path%2fto%2fca.crt") +# end-enable-tls-uri + +# start-modify-context +Mongo.tls_context_hooks.push( + Proc.new { |context| + context.ciphers = ["AES256-SHA"] + } +) +# end-modify-context From 53eff61de0fb9be89e8a294c500f44fa3e8f5554 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 15 Jan 2025 14:23:51 -0500 Subject: [PATCH 02/14] insecure tls --- source/connect.txt | 7 ++- source/connect/tls.txt | 88 +++++++++++++++++++++++++++++++--- source/includes/connect/tls.rb | 19 ++++++-- 3 files changed, 99 insertions(+), 15 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 65a2c3ff..2023001e 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -22,7 +22,6 @@ Connect to MongoDB :titlesonly: :maxdepth: 1 - /connect/mongoclient - /connect/stable-api - /connect/tls - \ No newline at end of file + Create a Client + Stable API + Configure TLS diff --git a/source/connect/tls.txt b/source/connect/tls.txt index a7650e58..f75c94ae 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -25,7 +25,7 @@ protocol to secure your connection to a MongoDB deployment. To connect to a MongoDB deployment using TLS, you must: -- Enable TLS connections in ``Mongo::Client``. +- Enable a TLS connection in ``Mongo::Client``. - Specify the client TLS certificate. - Specify the CA certificate to verify the server's TLS certificate. @@ -50,7 +50,7 @@ You can enable TLS for the connection to your MongoDB deployment in the followin - Set the ``ssl`` option to ``true`` in a new ``Mongo:Client`` object - Set the ``tls`` option to ``true`` in your connection string -.. note:: The {+driver-long+} does not support SSL +.. note:: SSL Naming Convention All {+mdb-server+} versions supported by the Ruby driver (2.6 and higher) only implement TLS. 2.6 and do not use SSL. @@ -68,16 +68,16 @@ You can enable TLS for the connection to your MongoDB deployment in the followin - ``ssl_cert``: The certificate file used to identify the connection against MongoDB. - ``ssl_key``: The private keyfile used to identify the connection against MongoDB. - - ``ssl_ca_cert``: The file containing the concatenated certificate authority (CA) - certificates used to validate certs passed from the other end of the connection. + - ``ssl_ca_cert``: The file containing the concatenated CA certificates + used to validate certs passed from the other end of the connection. By default, the driver will use the default system root certificate store as the trust anchor, if the option is not designated. These certificate options can be specified as different types. For example, the ``ssl_cert`` option has the alternative ``ssl_cert_object`` and ``ssl_cert_string`` options to specify the certificate file as either a certificate object or a string. - For more information on certificate options, see Options Hash section of - the API Documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__. + For more information on certificate options, see the Options Hash section of + the API Documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ . In the following example, the TLS certificate and corresponding private key are provided in separate files: @@ -88,7 +88,7 @@ You can enable TLS for the connection to your MongoDB deployment in the followin :start-after: start-enable-tls-settings :end-before: end-enable-tls-settings - The TLS certificate and private key can also be contained in the same file, but + The TLS certificate and private key can be contained in the same file, but both the certificate and private key options must still be specified. In the following example, the TLS certificate and the private key are both defined in the same ``client.pem`` file: @@ -161,6 +161,80 @@ The OCSP endpoint check may be disabled by setting the OCSP endpoint checking is not currently performed when running on JRuby, since JRuby does not correctly expose the OCSP endpoint URI. +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 ``sslVerify`` client option or the ``tlsInsecure`` +URI option to ``true``: + +.. tabs:: + + .. tab:: Mongo::Client + :tabid: mongoclient + + .. literalinclude:: /includes/connect/tls.rb + :language: ruby + :dedent: + :start-after: start-ssl-verify + :end-before: end-ssl-verify + + .. tab:: Connection String + :tabid: uri + + .. literalinclude:: /includes/connect/tls.rb + :language: ruby + :dedent: + :start-after: start-tls-insecure + :end-before: end-tls-insecure + +You can similarly set the following options to disable verification for the +certificate or hostname: + +.. tabs:: + + .. tab:: Mongo::Client + :tabid: mongoclient + + - ssl_verify_certificate: Disable certificate validation by setting the + option to ``false``. + - ssl_verify_hostname: Disable hostname verification by setting the option + to ``false``. + + .. tab:: Connection String + :tabid: uri + + - tlsAllowInvalidCertificates: Disable certificate validation by setting + the option to ``true``. + - tlsAllowInvalidHostnames: Disable hostname validation by setting + the option to ``true``. + +.. warning:: Don't Use Insecure TLS in Production + + Always disable insecure TLS in production. + + Enabling insecure TLS in a production environment makes your application + insecure and potentially vulnerable to expired certificates and foreign + processes posing as valid client instances. + .. _ruby-tls-api: API Documentation diff --git a/source/includes/connect/tls.rb b/source/includes/connect/tls.rb index eb3b22e5..7427f21e 100644 --- a/source/includes/connect/tls.rb +++ b/source/includes/connect/tls.rb @@ -1,14 +1,14 @@ # start-enable-tls-settings -client = Mongo::Client.new(["localhost:27017"], +client = Mongo::Client.new([":"], ssl: true, ssl_cert: 'path/to/client.crt', ssl_key: 'path/to/client.key', - ssl_ca_cert: 'path/to/ca.crt', + ssl_ca_cert: 'path/to/ca.crt' ) # end-enable-tls-settings # start-enable-tls-settings-same-file -client = Mongo::Client.new(["localhost:27017"], +client = Mongo::Client.new([":"], ssl: true, ssl_cert: 'path/to/client.pem', ssl_key: 'path/to/client.pem', @@ -18,7 +18,7 @@ # start-enable-tls-uri client = Mongo::Client.new( - "mongodb://localhost:27017/?tls=true&tlsCertificateKeyFile=path%2fto%2fclient.pem&tlsCAFile=path%2fto%2fca.crt") + "mongodb://:/?tls=true&tlsCertificateKeyFile=path%2fto%2fclient.pem&tlsCAFile=path%2fto%2fca.crt") # end-enable-tls-uri # start-modify-context @@ -28,3 +28,14 @@ } ) # end-modify-context + +# start-ssl-verify +client = Mongo::Client.new([":"], + ssl: true, + ssl_verify: false +) +# end-ssl-verify + +# start-tls-insecure +client = Mongo::Client.new('mongodb://:/?tls=true&tlsInsecure=true'); +# end-tls-insecure From aa0e740dcc9eb43aa23f982141c88fa5003bcbf3 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 15 Jan 2025 14:27:12 -0500 Subject: [PATCH 03/14] edits --- source/connect/tls.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index f75c94ae..c18f6681 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -64,7 +64,7 @@ You can enable TLS for the connection to your MongoDB deployment in the followin .. tab:: Mongo::Client :tabid: mongoclient - You must specify the following options for certificate paths: + To configure certificates, you must specify the following options: - ``ssl_cert``: The certificate file used to identify the connection against MongoDB. - ``ssl_key``: The private keyfile used to identify the connection against MongoDB. @@ -75,7 +75,7 @@ You can enable TLS for the connection to your MongoDB deployment in the followin These certificate options can be specified as different types. For example, the ``ssl_cert`` option has the alternative ``ssl_cert_object`` and ``ssl_cert_string`` - options to specify the certificate file as either a certificate object or a string. + options, to specify the certificate file as either a certificate object or a string. For more information on certificate options, see the Options Hash section of the API Documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ . @@ -102,7 +102,7 @@ You can enable TLS for the connection to your MongoDB deployment in the followin .. tab:: Connection String :tabid: uri - You must specify the following URI options: + To configure certificates, you must specify the following URI options: - ``tlsCertificateKeyFile``: The certificate and key file used to identify identify the connection against MongoDB. Both the certificate and key From 749241ac1681572145d5fff177cca1369bae325f Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 15 Jan 2025 14:35:43 -0500 Subject: [PATCH 04/14] monospace --- source/connect/tls.txt | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index c18f6681..7fc43f33 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -166,7 +166,7 @@ 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*. +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 @@ -214,17 +214,17 @@ certificate or hostname: .. tab:: Mongo::Client :tabid: mongoclient - - ssl_verify_certificate: Disable certificate validation by setting the + - ``ssl_verify_certificate``: Disable certificate validation by setting the option to ``false``. - - ssl_verify_hostname: Disable hostname verification by setting the option + - ``ssl_verify_hostname``: Disable hostname verification by setting the option to ``false``. .. tab:: Connection String :tabid: uri - - tlsAllowInvalidCertificates: Disable certificate validation by setting + - ``tlsAllowInvalidCertificates``: Disable certificate validation by setting the option to ``true``. - - tlsAllowInvalidHostnames: Disable hostname validation by setting + - ``tlsAllowInvalidHostnames``: Disable hostname validation by setting the option to ``true``. .. warning:: Don't Use Insecure TLS in Production @@ -235,8 +235,6 @@ certificate or hostname: insecure and potentially vulnerable to expired certificates and foreign processes posing as valid client instances. -.. _ruby-tls-api: - API Documentation ----------------- From 673a588009b4511420cd992be8b70ca2be354c76 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 15 Jan 2025 17:45:34 -0500 Subject: [PATCH 05/14] 1/2 MW edits --- source/connect/tls.txt | 66 ++++++++++++++++++++++-------------------- 1 file changed, 34 insertions(+), 32 deletions(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index 7fc43f33..67996452 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -23,11 +23,11 @@ Overview In this guide, you can learn how to use the Transport Layer Security (TLS) protocol to secure your connection to a MongoDB deployment. -To connect to a MongoDB deployment using TLS, you must: +To connect to a MongoDB deployment using TLS, you must perform the following steps: - Enable a TLS connection in ``Mongo::Client``. - Specify the client TLS certificate. -- Specify the CA certificate to verify the server's TLS certificate. +- Specify the Certificate Authority (CA) certificate to verify the server's TLS certificate. To learn how to configure your MongoDB deployment for TLS, see the :manual:`TLS configuration guide ` in the @@ -37,8 +37,8 @@ To learn how to configure your MongoDB deployment for TLS, see the 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. To - learn more about TLS, see the Wikipedia entry for :wikipedia:`Transport Layer Security `. + CAs is beyond the scope of this documentation. To learn more about TLS, see the + Wikipedia entry for :wikipedia:`Transport Layer Security `. .. _ruby-enable-tls: @@ -47,17 +47,17 @@ Enable TLS You can enable TLS for the connection to your MongoDB deployment in the following ways: -- Set the ``ssl`` option to ``true`` in a new ``Mongo:Client`` object -- Set the ``tls`` option to ``true`` in your connection string +- Set the ``ssl`` option to ``true`` in a new ``Mongo:Client`` object. +- Set the ``tls`` option to ``true`` in your connection string. .. note:: SSL Naming Convention - All {+mdb-server+} versions supported by the Ruby driver (2.6 and higher) - only implement TLS. 2.6 and do not use SSL. + All {+mdb-server+} versions supported by the {+driver-short+} v2.6 and later + implement only TLS. 2.6 and 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. + For historical reasons, the Ruby driver prefixes TLS options with ``ssl`` + instead of ``tls``. {+driver-short+} version 3.0 and later will use the + ``tls`` prefix for Ruby option names. .. tabs:: @@ -66,12 +66,14 @@ You can enable TLS for the connection to your MongoDB deployment in the followin To configure certificates, you must specify the following options: - - ``ssl_cert``: The certificate file used to identify the connection against MongoDB. - - ``ssl_key``: The private keyfile used to identify the connection against MongoDB. + - ``ssl_cert``: The certificate file used to verify the connection to + a MongoDB deployment. + - ``ssl_key``: The private keyfile used to verify the connection to + a MongoDB deployment. - ``ssl_ca_cert``: The file containing the concatenated CA certificates - used to validate certs passed from the other end of the connection. - By default, the driver will use the default system root certificate - store as the trust anchor, if the option is not designated. + used to validate certificates passed from the MongoDB deployment to the + client. If you don't specify a value for this option, the driver uses + the default system root certificate store as the trust anchor. These certificate options can be specified as different types. For example, the ``ssl_cert`` option has the alternative ``ssl_cert_object`` and ``ssl_cert_string`` @@ -88,7 +90,7 @@ You can enable TLS for the connection to your MongoDB deployment in the followin :start-after: start-enable-tls-settings :end-before: end-enable-tls-settings - The TLS certificate and private key can be contained in the same file, but + You can specify both the TLS certificate and private key in a single file, but both the certificate and private key options must still be specified. In the following example, the TLS certificate and the private key are both defined in the same ``client.pem`` file: @@ -104,13 +106,12 @@ You can enable TLS for the connection to your MongoDB deployment in the followin To configure certificates, you must specify the following URI options: - - ``tlsCertificateKeyFile``: The certificate and key file used to identify - identify the connection against MongoDB. Both the certificate and key - must be stored in the same file provided to this option. - - ``tlsCAFile``: The file containing the concatenated certificate authority (CA) - certificates used to validate certificates passed from the other end of the - connection. The driver will use the default system root certificate - store as the trust anchor, if the option is not designated. + - ``tlsCertificateKeyFile``: The file that contains the certificate and keyfile + used to verify the connection to a MongoDB deployment. + - ``tlsCAFile``: The file containing the concatenated CA certificates + used to validate certificates passed from the MongoDB deployment to the + client. If you don't specify a value for this option, the driver uses + the default system root certificate store as the trust anchor. .. literalinclude:: /includes/connect/tls.rb :language: ruby @@ -121,19 +122,19 @@ You can enable TLS for the connection to your MongoDB deployment in the followin The file containing the certificate and key usually has a``.crt`` or ``.pem`` extension. - URI option values must be properly URI escaped. This applies, for example, + URI option values must be percent-encoded. This applies, for example, to slashes (/) in the paths, which are encoded as ``%2f``. -Modify the SSL Context +Modify the TLS Context ---------------------- If your TLS configuration requires customization, you can set TLS context hooks -by adding a native Ruby class ``Proc`` object to the ``Mongo.tls_context_hooks`` -array. The ``Proc`` should be added to the array before creating any ``Mongo::Client`` +by adding a native Ruby ``Proc`` object to the ``Mongo.tls_context_hooks`` +array. Add the ``Proc`` object to the array before you create any ``Mongo::Client`` instances. -For example, the following code could be placed in an initializer to enable the -AES256-SHA cipher as the only cipher to be used for TLS: +The following code example enables the AES256-SHA cipher as the only cipher +to be used for TLS: .. literalinclude:: /includes/connect/tls.rb :language: ruby @@ -141,9 +142,10 @@ AES256-SHA cipher as the only cipher to be used for TLS: :start-after: start-modify-context :end-before: end-modify-context -To learn more about the SSL context options available, see the Ruby +To learn more about the TLS context options available, see the Ruby documentation for -`SSLContext `__. +`SSLContext `__ , +which the TLS options are based on . OCSP Verification ----------------- From 3eec0334d3b4a5e53adb683cef6c7ee71353f57a Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 16 Jan 2025 08:32:53 -0500 Subject: [PATCH 06/14] last of MW revisions and table --- source/connect/tls.txt | 79 +++++++++++++++++++++++++++++++++--------- 1 file changed, 62 insertions(+), 17 deletions(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index 67996452..7f391e1e 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -38,7 +38,7 @@ To learn how to configure your MongoDB deployment for TLS, see the 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 CAs is beyond the scope of this documentation. To learn more about TLS, see the - Wikipedia entry for :wikipedia:`Transport Layer Security `. + entry for :wikipedia:`Transport Layer Security ` . .. _ruby-enable-tls: @@ -73,13 +73,7 @@ You can enable TLS for the connection to your MongoDB deployment in the followin - ``ssl_ca_cert``: The file containing the concatenated CA certificates used to validate certificates passed from the MongoDB deployment to the client. If you don't specify a value for this option, the driver uses - the default system root certificate store as the trust anchor. - - These certificate options can be specified as different types. For example, the - ``ssl_cert`` option has the alternative ``ssl_cert_object`` and ``ssl_cert_string`` - options, to specify the certificate file as either a certificate object or a string. - For more information on certificate options, see the Options Hash section of - the API Documentation for `Mongo::Client <{+api-root+}/Mongo/Client.html>`__ . + the default system root certificate store as the trust anchor. In the following example, the TLS certificate and corresponding private key are provided in separate files: @@ -125,6 +119,56 @@ You can enable TLS for the connection to your MongoDB deployment in the followin URI option values must be percent-encoded. This applies, for example, to slashes (/) in the paths, which are encoded as ``%2f``. +Specify Client TLS Certificates +------------------------------- + +The {+driver-short+} provides multiple options for you to specify +the TLS certficate, key, and CA certificate with different data types: + +.. list-table:: + :header-rows: 1 + :widths: 30 20 50 + + * - Option Name + - Data/Object Type Accepted + - Description + * - ``:ssl_cert`` + - ``String`` + - The certificate file path used to identify the connection against MongoDB. + * - ``:ssl_cert_object`` + - ``OpenSSL::X509::Certificate`` + - An array of objects representing the certificate authority certificates + used to validate certificates passed from the other end of the connection. + * - ``:ssl_cert_string`` + - String + - A string containing the PEM-encoded certificate used to identify the + connection against MongoDB. + * - ``:ssl_key`` + - String + - The private keyfile path used to identify the connection against MongoDB. + * - ``:ssl_key_object`` + - OpenSSL::PKey + - The private key object used to identify the connection against MongoDB + * - ``:ssl_key_pass_phrase`` + - String + - A passphrase for the private key. + * - ``:ssl_key_string`` + - String + - A string containing the PEM-encoded private key used to identify the + connection against MongoDB. + * - ``:ssl_ca_cert`` + - String + - The file path containing concatenated CA certificates used to validate certificates + passed from the other end of the connection. + * - ``:ssl_ca_cert_object`` + - Array + - An array of objects representing the certificate authority certificates used + to validate certs passed from the other end of the connection. + * - ``:ssl_ca_cert_string`` + - String + - A string containing the PEM-encoded, concatenated CA certificates used to validate certificates + passed from the other end of the connection. + Modify the TLS Context ---------------------- @@ -145,23 +189,24 @@ to be used for TLS: To learn more about the TLS context options available, see the Ruby documentation for `SSLContext `__ , -which the TLS options are based on . +which the {+driver-short+} TLS options are based on. OCSP Verification ----------------- If the certificate provided by the server contains an OCSP endpoint URI, -the driver will issue an OCSP request to the specified endpoint to verify the -validity of the certificate by default. +the driver issues an Online Certificate Status Protocol (OCSP) request to +the specified endpoint by default to verify the validity of the certificate. -The OCSP endpoint check may be disabled by setting the -``:ssl_verify_ocsp_endpoint`` Ruby option to ``false`` or by setting the -``tlsDisableOCSPEndpointCheck`` URI option to ``true`` when creating a client. +To disable the OCSP endpoint check, set the ``:ssl_verify_ocsp_endpoint`` +Ruby option to ``false`` or set the ``tlsDisableOCSPEndpointCheck`` URI option +to ``true`` when creating a client. -.. note:: +.. note:: JRuby Does Not Support OCSP Verification - OCSP endpoint checking is not currently performed when running on JRuby, - since JRuby does not correctly expose the OCSP endpoint URI. + Because JRuby does not correctly expose OCSP endpoint URIs, + the driver does not check OCSP endpoints when the underlying + application runs on JRuby. Allow Insecure TLS ------------------ From 3693caad3117090b78969133f0c97d2710a88e02 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 16 Jan 2025 08:52:27 -0500 Subject: [PATCH 07/14] table reformat --- source/connect/tls.txt | 78 ++++++++++++++++++++++++++++++------------ 1 file changed, 56 insertions(+), 22 deletions(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index 7f391e1e..5bbad14d 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -123,51 +123,85 @@ Specify Client TLS Certificates ------------------------------- The {+driver-short+} provides multiple options for you to specify -the TLS certficate, key, and CA certificate with different data types: +the TLS certificate, key, and CA certificate with different data or object types. + +TLS Certificate +~~~~~~~~~~~~~~~ + +You may provide one of the following options to specify the TLS certificate: .. list-table:: :header-rows: 1 - :widths: 30 20 50 + :widths: 20 30 50 * - Option Name - Data/Object Type Accepted - Description * - ``:ssl_cert`` - ``String`` - - The certificate file path used to identify the connection against MongoDB. + - The certificate file path used to verify the connection to a MongoDB + deployment. * - ``:ssl_cert_object`` - ``OpenSSL::X509::Certificate`` - - An array of objects representing the certificate authority certificates - used to validate certificates passed from the other end of the connection. + - The certificate object used to to verify the connection to a MongoDB + deployment. * - ``:ssl_cert_string`` - - String - - A string containing the PEM-encoded certificate used to identify the - connection against MongoDB. + - ``String`` + - A string containing the PEM-encoded certificate used to verify the connection to + a MongoDB deployment. + +TLS Private Key +~~~~~~~~~~~~~~~ + +You may provide one of the following options to specify the TLS private key: + +.. list-table:: + :header-rows: 1 + :widths: 20 30 50 + + * - Option Name + - Data/Object Type Accepted + - Description * - ``:ssl_key`` - - String - - The private keyfile path used to identify the connection against MongoDB. + - ``String`` + - The private keyfile path used to verify the connection to a MongoDB + deployment. * - ``:ssl_key_object`` - - OpenSSL::PKey - - The private key object used to identify the connection against MongoDB + - ``OpenSSL::PKey`` + - The private key object used to verify the connection to a MongoDB + deployment. * - ``:ssl_key_pass_phrase`` - - String + - ``String`` - A passphrase for the private key. * - ``:ssl_key_string`` - - String - - A string containing the PEM-encoded private key used to identify the - connection against MongoDB. + - ``String`` + - A string containing the PEM-encoded private key used to verify the + connection to a MongoDB deployment. + +TLS CA Certificate +~~~~~~~~~~~~~~~~~~ + +You may provide one of the following options to specify the TLS CA certificate: + +.. list-table:: + :header-rows: 1 + :widths: 20 30 50 + + * - Option Name + - Data/Object Type Accepted + - Description * - ``:ssl_ca_cert`` - - String + - ``String`` - The file path containing concatenated CA certificates used to validate certificates - passed from the other end of the connection. + passed from the MongoDB deployment to the client. * - ``:ssl_ca_cert_object`` - - Array + - ``Array`` - An array of objects representing the certificate authority certificates used - to validate certs passed from the other end of the connection. + to validate certs passed from the MongoDB deployment to the client. * - ``:ssl_ca_cert_string`` - - String + - ``String`` - A string containing the PEM-encoded, concatenated CA certificates used to validate certificates - passed from the other end of the connection. + passed from the MongoDB deployment to the client. Modify the TLS Context ---------------------- From 0246516895b3b65f8849a734c1979da98af62836 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 16 Jan 2025 09:11:53 -0500 Subject: [PATCH 08/14] spacing edit --- source/connect/tls.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index 5bbad14d..f2f43f00 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -38,7 +38,7 @@ To learn how to configure your MongoDB deployment for TLS, see the 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 CAs is beyond the scope of this documentation. To learn more about TLS, see the - entry for :wikipedia:`Transport Layer Security ` . + Wikipedia entry for :wikipedia:`Transport Layer Security`. .. _ruby-enable-tls: From 610f98948ed2b70f7d9e2089d7222d85f9a61c7c Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 16 Jan 2025 09:17:56 -0500 Subject: [PATCH 09/14] formatting edits --- source/connect/tls.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index f2f43f00..a096cc00 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -38,7 +38,7 @@ To learn how to configure your MongoDB deployment for TLS, see the 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 CAs is beyond the scope of this documentation. To learn more about TLS, see the - Wikipedia entry for :wikipedia:`Transport Layer Security`. + Wikipedia entry for :wikipedia:`Transport Layer Security` . .. _ruby-enable-tls: @@ -196,11 +196,11 @@ You may provide one of the following options to specify the TLS CA certificate: passed from the MongoDB deployment to the client. * - ``:ssl_ca_cert_object`` - ``Array`` - - An array of objects representing the certificate authority certificates used - to validate certs passed from the MongoDB deployment to the client. + - An array of objects representing the CA certificates used + to validate certificates passed from the MongoDB deployment to the client. * - ``:ssl_ca_cert_string`` - ``String`` - - A string containing the PEM-encoded, concatenated CA certificates used to validate certificates + - A string containing the PEM-encoded CA certificate used to validate certificates passed from the MongoDB deployment to the client. Modify the TLS Context From 65c03063a7167a6b2af82744755aa9217b1f45ed Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 16 Jan 2025 09:31:59 -0500 Subject: [PATCH 10/14] format --- source/connect/tls.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index a096cc00..5ca3de12 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -38,7 +38,7 @@ To learn how to configure your MongoDB deployment for TLS, see the 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 CAs is beyond the scope of this documentation. To learn more about TLS, see the - Wikipedia entry for :wikipedia:`Transport Layer Security` . + Wikipedia entry for :wikipedia:`Transport Layer Security ` . .. _ruby-enable-tls: @@ -200,7 +200,7 @@ You may provide one of the following options to specify the TLS CA certificate: to validate certificates passed from the MongoDB deployment to the client. * - ``:ssl_ca_cert_string`` - ``String`` - - A string containing the PEM-encoded CA certificate used to validate certificates + - A string containing one PEM-encoded CA certificate used to validate certificates passed from the MongoDB deployment to the client. Modify the TLS Context @@ -220,10 +220,10 @@ to be used for TLS: :start-after: start-modify-context :end-before: end-modify-context -To learn more about the TLS context options available, see the Ruby +The {+driver-short+} TLS options are based on native Ruby handling of SSL. To +learn more about the TLS context options available, see the Ruby documentation for -`SSLContext `__ , -which the {+driver-short+} TLS options are based on. +`SSLContext `__. OCSP Verification ----------------- From f4dda225e7f42edcc06b2e815aed97ebb69a989e Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 16 Jan 2025 09:39:24 -0500 Subject: [PATCH 11/14] edit --- source/connect/tls.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index 5ca3de12..7a4fc0be 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -220,7 +220,7 @@ to be used for TLS: :start-after: start-modify-context :end-before: end-modify-context -The {+driver-short+} TLS options are based on native Ruby handling of SSL. To +The {+driver-short+} TLS context options are based on native Ruby handling of SSL. To learn more about the TLS context options available, see the Ruby documentation for `SSLContext `__. From 38674341a0e33588c1461cdf14f98b88f4879494 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 17 Jan 2025 13:32:32 -0500 Subject: [PATCH 12/14] MW last comments --- source/connect/tls.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/connect/tls.txt b/source/connect/tls.txt index 7a4fc0be..caad2195 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -38,7 +38,7 @@ To learn how to configure your MongoDB deployment for TLS, see the 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 CAs is beyond the scope of this documentation. To learn more about TLS, see the - Wikipedia entry for :wikipedia:`Transport Layer Security ` . + Wikipedia entry for :wikipedia:`Transport Layer Security `. .. _ruby-enable-tls: @@ -128,7 +128,7 @@ the TLS certificate, key, and CA certificate with different data or object types TLS Certificate ~~~~~~~~~~~~~~~ -You may provide one of the following options to specify the TLS certificate: +You can provide one of the following options to specify the TLS certificate: .. list-table:: :header-rows: 1 @@ -143,7 +143,7 @@ You may provide one of the following options to specify the TLS certificate: deployment. * - ``:ssl_cert_object`` - ``OpenSSL::X509::Certificate`` - - The certificate object used to to verify the connection to a MongoDB + - The certificate object used to verify the connection to a MongoDB deployment. * - ``:ssl_cert_string`` - ``String`` @@ -153,7 +153,7 @@ You may provide one of the following options to specify the TLS certificate: TLS Private Key ~~~~~~~~~~~~~~~ -You may provide one of the following options to specify the TLS private key: +You can provide one of the following options to specify the TLS private key: .. list-table:: :header-rows: 1 @@ -181,7 +181,7 @@ You may provide one of the following options to specify the TLS private key: TLS CA Certificate ~~~~~~~~~~~~~~~~~~ -You may provide one of the following options to specify the TLS CA certificate: +You can provide one of the following options to specify the TLS CA certificate: .. list-table:: :header-rows: 1 From 083e7f57a67eff81665a87a6e453e3191837ee74 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 17 Jan 2025 17:56:38 -0500 Subject: [PATCH 13/14] small change --- source/monitoring/cluster-monitoring.txt | 47 ++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 source/monitoring/cluster-monitoring.txt diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt new file mode 100644 index 00000000..fc392bfb --- /dev/null +++ b/source/monitoring/cluster-monitoring.txt @@ -0,0 +1,47 @@ +.. _ruby-cluster-monitoring: + +================== +Cluster Monitoring +================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, server, topology + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecols + +Overview +-------- + +The driver allows the application to be notified when certain events happen. These +events are organized into the following categories: + +- Command Monitoring + +- Server Discovery and Monitoring (SDAM) + +- Connection Pools and Connections + +Command Monitoring +------------------ + +SDAM +---- + +SDAM Event Descriptions +~~~~~~~~~~~~~~~~~~~~~~~ + +Connection Pools and Connections +-------------------------------- + +Excluded and Redacted Events +---------------------------- + + From b64d746d9ad9ec35697f9abd329cf5e84d7d5190 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 17 Jan 2025 18:00:11 -0500 Subject: [PATCH 14/14] tech review --- source/connect/tls.txt | 2 +- source/includes/connect/tls.rb | 2 +- source/monitoring/cluster-monitoring.txt | 47 ------------------------ 3 files changed, 2 insertions(+), 49 deletions(-) delete mode 100644 source/monitoring/cluster-monitoring.txt diff --git a/source/connect/tls.txt b/source/connect/tls.txt index caad2195..77a0508a 100644 --- a/source/connect/tls.txt +++ b/source/connect/tls.txt @@ -223,7 +223,7 @@ to be used for TLS: The {+driver-short+} TLS context options are based on native Ruby handling of SSL. To learn more about the TLS context options available, see the Ruby documentation for -`SSLContext `__. +`SSLContext `__. OCSP Verification ----------------- diff --git a/source/includes/connect/tls.rb b/source/includes/connect/tls.rb index 7427f21e..99f885e8 100644 --- a/source/includes/connect/tls.rb +++ b/source/includes/connect/tls.rb @@ -37,5 +37,5 @@ # end-ssl-verify # start-tls-insecure -client = Mongo::Client.new('mongodb://:/?tls=true&tlsInsecure=true'); +client = Mongo::Client.new('mongodb://:/?tls=true&tlsInsecure=true') # end-tls-insecure diff --git a/source/monitoring/cluster-monitoring.txt b/source/monitoring/cluster-monitoring.txt deleted file mode 100644 index fc392bfb..00000000 --- a/source/monitoring/cluster-monitoring.txt +++ /dev/null @@ -1,47 +0,0 @@ -.. _ruby-cluster-monitoring: - -================== -Cluster Monitoring -================== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code example, server, topology - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecols - -Overview --------- - -The driver allows the application to be notified when certain events happen. These -events are organized into the following categories: - -- Command Monitoring - -- Server Discovery and Monitoring (SDAM) - -- Connection Pools and Connections - -Command Monitoring ------------------- - -SDAM ----- - -SDAM Event Descriptions -~~~~~~~~~~~~~~~~~~~~~~~ - -Connection Pools and Connections --------------------------------- - -Excluded and Redacted Events ----------------------------- - -