-
Notifications
You must be signed in to change notification settings - Fork 33
/
Copy pathtls.txt
213 lines (148 loc) · 6.61 KB
/
tls.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
.. _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 <golang-enable-tls>` describes ways to enable TLS on
your connection
- :ref:`Configure Certificates <golang-configure-tls-certificates>`
describes the certificates required to configure TLS
- :ref:`Reference Certificates in a Client <golang-client-tls-connect>`
provides an example of how to create a ``Config`` struct to configure your
TLS options
- :ref:`Additional Information <golang-tls-addtl-info>`
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 <w/index.php?title=Transport_Layer_Security&oldid=1184063676>`.
.. _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://<hostname>:<port>?tls=true"
opts := options.Client().ApplyURI(uri)
client, _ := mongo.Connect(opts)
.. tab:: ClientOptions
:tabid: clientoptions tls true
.. code-block:: go
:emphasize-lines: 2
uri := "<connection string>"
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 <https://pkg.go.dev/crypto/tls#Config>`__.
.. _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) </core/security-transport-encryption/>`
- :manual:`TLS/SSL Configuration for Clients </tutorial/configure-ssl-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 <https://pkg.go.dev/crypto/tls>`__
- `x509 package <https://pkg.go.dev/crypto/x509>`__