diff --git a/source/archive-reference-files/fundamentals/connections/tls.txt b/source/archive-reference-files/fundamentals/connections/tls.txt deleted file mode 100644 index 96ca46ca..00000000 --- a/source/archive-reference-files/fundamentals/connections/tls.txt +++ /dev/null @@ -1,213 +0,0 @@ -.. _golang-tls: - -======================== -Enable and Configure TLS -======================== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code example, security, connection options - :description: Learn how to secure your MongoDB connection using TLS by enabling TLS options and configuring certificates in your Go application. - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -Overview --------- - -In this guide, you can learn how to use the TLS protocol to secure -your connection to a MongoDB deployment. To configure your connection to -use TLS, enable the TLS option and provide your certificates for -validation when creating a client. - -This guide includes the following sections: - -- :ref:`Enable TLS ` describes ways to enable TLS on - your connection - -- :ref:`Configure Certificates ` - describes the certificates required to configure TLS - -- :ref:`Reference Certificates in a Client ` - provides an example of how to create a ``Config`` struct to configure your - TLS options - -- :ref:`Additional Information ` - provides links to resources and API documentation for types - and methods mentioned in this guide - -.. tip:: - - To learn more about TLS, see the Wikipedia entry on - :wikipedia:`Transport Layer Security `. - -.. _golang-enable-tls: - -Enable TLS ----------- - -You can enable TLS on a connection to your MongoDB instance -in one of the following ways: - -- Setting the ``tls`` option to ``true`` in your connection string -- Passing an empty ``Config`` struct to the ``SetTLSConfig()`` - method when creating a ``ClientOptions`` instance - -Select from the following :guilabel:`Connection String` and -:guilabel:`ClientOptions` tabs to see a corresponding code sample: - -.. tabs:: - - .. tab:: Connection String - :tabid: connection string tls true - - .. code-block:: go - :emphasize-lines: 1 - - uri := "mongodb://:?tls=true" - opts := options.Client().ApplyURI(uri) - client, _ := mongo.Connect(opts) - - .. tab:: ClientOptions - :tabid: clientoptions tls true - - .. code-block:: go - :emphasize-lines: 2 - - uri := "" - opts := options.Client().ApplyURI(uri).SetTLSConfig(&tls.Config{}) - client, _ := mongo.Connect(opts) - -.. note:: - - If your connection string uses a DNS SRV record by including - the ``mongodb+srv`` prefix, TLS is enabled on your connection by - default. - -To view a full list of client options, see :ref:`golang-connection-options`. - -.. _golang-configure-tls-certificates: - -Configure Certificates ----------------------- - -To successfully initiate a TLS request, your application must present -cryptographic certificates to prove its identity. Your application's -certificates must be stored as PEM files to enable TLS when connecting. - -.. important:: - - For production use, we recommend that your MongoDB deployment use valid - certificates generated and signed by the same certificate authority. - For testing, your deployment can use self-signed certificates. - -The following list describes the components that your client must -present to establish a TLS-enabled connection: - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - - * - TLS Component - - Description - - * - Certificate Authority (CA) - - One or more certificate authorities to - trust when making a TLS connection. - - * - Client Certificate - - A digital certificate that allows the server to verify the identity - of your application to establish an encrypted network connection. - - * - Certificate Key - - The client certificate private key file. This key is often - included within the certificate file itself. - - * - Passphrase - - The password to decrypt the private client key if it is encrypted. - -.. _golang-client-tls-connect: - -Reference Certificates in a Client ----------------------------------- - -You must reference your certificates in your ``ClientOptions`` -object so that the server can validate them before the client connects. -We recommend that you set the ``TLSConfig`` field of your -``ClientOptions`` instance to a ``Config`` struct to configure your -TLS connection. ``Config`` structs are native to Go and allow you to keep -all your TLS options in a single reusable object. - -To create a ``Config`` instance, import the ``crypto/tls`` and -``crypto/x509`` packages. Next, create a ``Config`` struct instance and -set the relevant struct fields for your configuration. - -Within your ``Config`` instance, you can set optional -fields to configure TLS on your connection. For **testing purposes**, -you can set the ``InsecureSkipVerify`` field to ``true``. - -.. warning:: - - Setting the ``InsecureSkipVerify`` field to ``true`` disables - both certificate and hostname validation. - - Specifying this option in a production environment makes - your application insecure and potentially - vulnerable to expired certificates and foreign processes posing - as valid client instances. - -To learn more about the ``Config`` struct, see the `tls.Config API -documentation `__. - -.. _golang-tls-config-full-example: - -Example -~~~~~~~ - -This example performs the following actions to create a ``Config`` -instance and a ``Client`` instance with TLS enabled: - -1. Creates variables to reference the certificate filepaths - -#. Creates a CA file pool by using the ``x509.NewCertPool()`` method - and appends the contents of the CA file - -#. Loads the client certificate files by using the - ``tls.LoadX509KeyPair()`` method - -#. Instantiates a ``Config`` struct and sets the ``RootCAs`` and - ``Certificates`` fields - -#. Passes the ``Config`` instance to the ``SetTLSConfig()`` method to - set the ``TLSConfig`` field of the ``ClientOptions`` - -.. literalinclude:: /includes/fundamentals/code-snippets/tls.go - :language: go - -.. _golang-tls-addtl-info: - -Additional Information ----------------------- - -To learn more about enabling TLS on a connection, see the -following Server manual documentation: - -- :manual:`TLS/SSL (Transport Encryption) ` -- :manual:`TLS/SSL Configuration for Clients ` - -API Documentation -~~~~~~~~~~~~~~~~~ - -To learn more about the methods and types mentioned in this -guide, see the following API documentation: - -- `ClientOptions <{+api+}/mongo/options#ClientOptions>`__ -- `SetTLSConfig() <{+api+}/mongo/options#ClientOptions.SetTLSConfig>`__ -- `tls package `__ -- `x509 package `__ diff --git a/source/includes/fundamentals/code-snippets/tls.go b/source/includes/fundamentals/code-snippets/tls.go index 83b19b7d..c255d307 100644 --- a/source/includes/fundamentals/code-snippets/tls.go +++ b/source/includes/fundamentals/code-snippets/tls.go @@ -13,6 +13,7 @@ import ( func main() { + // start-tls caFile := "" certFile := "" keyFile := "" @@ -43,6 +44,7 @@ func main() { // Sets TLS options in options instance opts := options.Client().ApplyURI(uri).SetTLSConfig(tlsConfig) + // end-tls // Connects to MongoDB with TLS enabled client, err := mongo.Connect(opts) diff --git a/source/security/tls.txt b/source/security/tls.txt index 2eb2b2d3..27bce705 100644 --- a/source/security/tls.txt +++ b/source/security/tls.txt @@ -4,4 +4,224 @@ Enable TLS on a Connection ========================== -.. TODO \ No newline at end of file +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, security, connection options + :description: Learn how to secure your MongoDB connection by using TLS in your Go application. + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use the TLS protocol to secure +your connection to a MongoDB deployment. To configure your connection to +use TLS, enable the TLS option and provide your certificates for +validation when creating a client. + +This guide includes the following sections: + +- :ref:`Enable TLS ` describes ways to enable TLS on + your connection + +- :ref:`Configure Certificates ` + describes the certificates required to configure TLS + +- :ref:`Reference Certificates in a Client ` + provides an example of how to create a ``tls.Config`` struct to configure your + TLS options + +- :ref:`Additional Information ` + provides links to resources and API documentation for types + and methods mentioned in this guide + +.. tip:: + + To learn more about TLS, see the Wikipedia entry on + :wikipedia:`Transport Layer Security `. + +.. _golang-enable-tls: + +Enable TLS +---------- + +You can enable TLS on a connection to your MongoDB instance +in one of the following ways: + +- Setting the ``tls`` option to ``true`` in your connection string +- Passing an empty ``tls.Config`` struct to the ``SetTLSConfig()`` + method when creating a ``ClientOptions`` instance + +Select from the following :guilabel:`Connection String` and +:guilabel:`ClientOptions` tabs to see a corresponding code sample: + +.. tabs:: + + .. tab:: Connection String + :tabid: connection string tls true + + .. code-block:: go + :emphasize-lines: 1 + + uri := "mongodb://:?tls=true" + opts := options.Client().ApplyURI(uri) + client, _ := mongo.Connect(opts) + + .. tab:: ClientOptions + :tabid: clientoptions tls true + + .. code-block:: go + :emphasize-lines: 2 + + uri := "" + opts := options.Client().ApplyURI(uri).SetTLSConfig(&tls.Config{}) + client, _ := mongo.Connect(opts) + +.. note:: + + If you use a DNS SRV record when connecting to MongoDB by specifying + the ``+srv`` modification in your connection string, you enable + TLS on your connection by default. To disable it, set the ``tls`` or ``ssl`` parameter + value to ``false`` in your connection string or ``ClientOptions`` object. + + To learn more about connection behavior when you use a DNS seedlist, + see the :manual:`SRV Connection Format ` + section in the {+mdb-server+}. + +To view a full list of client options, see the +:ref:`golang-connection-options` guides. + +.. _golang-configure-tls-certificates: + +Configure Certificates +---------------------- + +To successfully initiate a TLS request, your application must present +cryptographic certificates to prove its identity. Your application's +certificates must be stored as PEM files to enable TLS when connecting. + +.. important:: Use Valid Certificates in Production + + For production use, we recommend that your MongoDB deployment use valid + certificates generated and signed by the same certificate authority. + For testing, your deployment can use self-signed certificates. + +The following list describes the components that your client must +present to establish a TLS-enabled connection: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - TLS Component + - Description + + * - Certificate Authority (CA) + - One or more certificate authorities to + trust when making a TLS connection. + + * - Client Certificate + - A digital certificate that allows the server to verify the identity + of your application to establish an encrypted network connection. + + * - Certificate Key + - The client certificate private key file. This key is often + included within the certificate file itself. + + * - Passphrase + - The password to decrypt the private client key if it is encrypted. + +.. _golang-client-tls-connect: + +Reference Certificates in a Client +---------------------------------- + +You must reference your certificates in your ``ClientOptions`` +object so that the server can validate them before the client connects. + +We recommend that you set the ``TLSConfig`` field of your +``ClientOptions`` instance to a ``tls.Config`` struct to configure your +TLS connection. ``tls.Config`` structs are native to Go and allow you to keep +all your TLS options in a single reusable object. + +To create a ``tls.Config`` instance, import the ``crypto/tls`` and +``crypto/x509`` packages. Next, create a ``tls.Config`` struct instance and +set the relevant struct fields for your configuration, as shown in the +following section. + +To learn more about the ``tls.Config`` struct, see the `tls.Config API +documentation `__. + +.. _golang-tls-config-full-example: + +Example +~~~~~~~ + +This example performs the following actions to create a ``tls.Config`` +instance and a ``Client`` instance with TLS enabled: + +1. Creates variables to reference the certificate filepaths + +#. Creates a CA file pool by using the ``x509.NewCertPool()`` method + and appends the contents of the CA file + +#. Loads the client certificate files by using the + ``tls.LoadX509KeyPair()`` method + +#. Instantiates a ``tls.Config`` struct and sets the ``RootCAs`` and + ``Certificates`` fields + +#. Passes the ``tls.Config`` instance to the ``SetTLSConfig()`` method to + set the ``TLSConfig`` field of the ``ClientOptions`` + +.. literalinclude:: /includes/fundamentals/code-snippets/tls.go + :language: go + :start-after: start-tls + :end-before: end-tls + :dedent: + +Insecure Option +~~~~~~~~~~~~~~~ + +Within your ``tls.Config`` instance, you can set optional +fields to configure TLS on your connection. For **testing purposes**, +you can set the ``InsecureSkipVerify`` field to ``true``. + +.. warning:: + + Setting the ``InsecureSkipVerify`` field to ``true`` disables + both certificate and hostname validation. + + Specifying this option in a production environment makes + your application insecure and potentially + vulnerable to expired certificates and foreign processes posing + as valid client instances. + +.. _golang-tls-addtl-info: + +Additional Information +---------------------- + +To learn more about enabling TLS on a connection, see the +following documentation in the {+mdb-server+} manual: + +- :manual:`TLS/SSL (Transport Encryption) ` +- :manual:`TLS/SSL Configuration for Clients ` + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the methods and types mentioned in this +guide, see the following API documentation: + +- `ClientOptions <{+api+}/mongo/options#ClientOptions>`__ +- `SetTLSConfig() <{+api+}/mongo/options#ClientOptions.SetTLSConfig>`__ +- `tls package `__ +- `x509 package `__