Skip to content

Commit 8a80354

Browse files
mongoKartmongoKart
authored
[DOCSP-24541] TLS page (#40)
* first commit * other changes * wip * wip * add to toc * remove tables * fixes * fix link * feedback * autobuilder
1 parent b50c5f1 commit 8a80354

File tree

4 files changed

+236
-0
lines changed

4 files changed

+236
-0
lines changed

‎snooty.toml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
1717
driver-long = "MongoDB .NET/C# Driver"
1818
driver-short = ".NET/C# Driver"
1919
lang-framework = ".NET/C#"
20+
framework = ".NET framework"
21+
framework-version = "4.8"
22+
standard-version = "2.1"
2023
language = "C#"
2124
mongo-community = "MongoDB Community Edition"
2225
mongo-enterprise = "MongoDB Enterprise Edition"

‎source/fundamentals/connection.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Connection
1010

1111
/fundamentals/connection/connect
1212
/fundamentals/connection/connection-options
13+
/fundamentals/connection/tls
1314

1415
.. contents:: On this page
1516
:local:

‎source/fundamentals/connection/connection-options.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ This section describes the MongoDB connection and authentication options
1414
available in the {+driver-short+}. You can configure your connection using either
1515
the connection URI or a ``MongoClientSettings`` object.
1616

17+
.. _csharp-connection-uri:
18+
1719
----------------------------------
1820
Using the Connection URI
1921
----------------------------------
@@ -27,6 +29,8 @@ and the ``tls`` option with a value of ``true``:
2729
:language: csharp
2830
:dedent:
2931

32+
.. _csharp-mongo-client-settings:
33+
3034
-----------------------------
3135
Using ``MongoClientSettings``
3236
-----------------------------

‎source/fundamentals/connection/tls.txt‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
.. _csharp-tls:
2+
3+
==========================
4+
Enable TLS on a Connection
5+
==========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn how to connect to MongoDB instances with the
17+
:wikipedia:`TLS/SSL <Transport_Layer_Security>`
18+
security protocol using the underlying TLS/SSL support in the {+framework+}. To
19+
configure your connection to use TLS/SSL, enable the TLS/SSL settings in either
20+
the :ref:`connection string <csharp-connection-uri>` or
21+
:ref:`MongoClientSettings <csharp-mongo-client-settings>`.
22+
23+
.. _csharp-tls-enable:
24+
25+
Enable TLS
26+
----------
27+
28+
You can enable TLS for the connection to your MongoDB instance
29+
in two different ways: using a property on a ``MongoClientSettings`` object or
30+
through a parameter in your connection string.
31+
32+
.. tabs::
33+
34+
.. tab:: MongoClientSettings
35+
:tabid: mongoclientsettings
36+
37+
To enable TLS with a ``MongoClientSettings`` object, set the ``UseTls`` property
38+
to ``true``:
39+
40+
.. code-block:: csharp
41+
42+
var settings = new MongoClientSettings() { UseTls = true };
43+
var client = new MongoClient(settings);
44+
45+
.. tab:: Connection String
46+
:tabid: connectionstring
47+
48+
To enable TLS with a connection string, assign the
49+
parameter ``tls`` a value of ``true`` in the connection string passed to the
50+
``MongoClient`` constructor:
51+
52+
.. code-block:: csharp
53+
54+
var mongoClient = new MongoClient("mongodb://<username>:<password>@<hostname>:<port>?tls=true");
55+
56+
Configure a Client Certificate
57+
------------------------------
58+
59+
You can configure your X.509 certificate using ``MongoClientSettings``. The following
60+
code sample creates a new X.509 certificate object using the certificate file named
61+
``client.pfx``, which is protected by the password ``mySuperSecretPassword``. The code
62+
then adds this certificate to the ``SslSettings.ClientCertificates`` array in
63+
``MongoClientSettings``.
64+
65+
.. code-block:: csharp
66+
67+
var cert = new X509Certificate2("client.pfx", "mySuperSecretPassword");
68+
69+
var settings = new MongoClientSettings
70+
{
71+
SslSettings = new SslSettings
72+
{
73+
ClientCertificates = new[] { cert }
74+
},
75+
UseTls = true
76+
};
77+
78+
.. important::
79+
80+
When loading a certificate with a password, the certificate object must contain a private
81+
key. If it doesn't, your certificate will not be passed to the server.
82+
83+
Allow Insecure TLS
84+
------------------
85+
86+
When TLS is enabled, the {+driver-short+} automatically verifies the certificate that
87+
the server presents. When testing your code, you can disable certificate verification.
88+
This is known as *insecure TLS.*
89+
90+
When using insecure TLS, the only requirement is that the server present an X.509
91+
certificate. The driver will accept a certificate even if any of the following are true:
92+
93+
- The hostname of the server and the subject name (or subject alternative name)
94+
on the certificate don't match.
95+
- The certificate is expired or not yet valid.
96+
- The certificate doesn't have a trusted root certificate in the chain.
97+
- The certificate purpose isn't valid for server identification.
98+
99+
You can allow insecure TLS in two different ways: using a property on a
100+
``MongoClientSettings`` object or through a parameter in your connection string.
101+
102+
.. tabs::
103+
104+
.. tab:: MongoClientSettings
105+
:tabid: mongoclientsettings
106+
107+
To allow insecure TLS with a ``MongoClientSettings``
108+
object, set the ``AllowInsecureTls`` property to ``true``:
109+
110+
.. code-block:: csharp
111+
:emphasize-lines: 4
112+
113+
var settings = new MongoClientSettings
114+
{
115+
UseTls = true,
116+
AllowInsecureTls = true
117+
};
118+
var client = new MongoClient(settings);
119+
120+
.. tab:: Connection String
121+
:tabid: connectionstring
122+
123+
To allow insecure TLS using a connection string,
124+
assign the connection string parameter ``tlsInsecure`` a value of ``true``:
125+
126+
.. code-block:: csharp
127+
128+
var mongoClient = new MongoClient("mongodb://<username>:<password>@<hostname>:<port>?tls=true&tlsInsecure=true");
129+
130+
.. warning::
131+
132+
Always set this option to ``false`` in production. For security reasons, it's
133+
important that the server certificate is properly validated.
134+
135+
.. _tls_configure-certificates:
136+
137+
Check Certificate Revocation
138+
----------------------------
139+
140+
When an X.509 certificate should no longer be trusted--for example, if its private key
141+
has been compromised--the certificate authority will revoke the certificate.
142+
143+
By default, the {+driver-short+} doesn't check whether a server's certificate has been
144+
revoked before it connects. You can enable revocation checking using either
145+
``MongoClientSettings`` or the connection string.
146+
147+
.. tabs::
148+
149+
.. tab:: MongoClientSettings
150+
:tabid: mongoclientsettings
151+
152+
To enable revocation checking using ``MongoClientSettings``, set
153+
``SslSettings.CheckCertificateRevocation`` to ``true``:
154+
155+
.. code-block:: csharp
156+
:emphasize-lines: 5
157+
158+
var settings = new MongoClientSettings
159+
{
160+
SslSettings = new SslSettings
161+
{
162+
CheckCertificateRevocation = true
163+
},
164+
UseTls = true
165+
};
166+
167+
.. tab:: Connection String
168+
:tabid: connectionstring
169+
170+
To enable revocation checking using a connection string,
171+
assign the connection string parameter ``tlsDisableCertificateRevocationCheck``
172+
a value of ``false``:
173+
174+
.. code-block:: csharp
175+
176+
var mongoClient = new MongoClient("mongodb://<username>:<password>@<hostname>:<port>?tls=true&tlsDisableCertificateRevocationCheck=false");
177+
178+
.. note::
179+
180+
The {+driver-short+} doesn't check revocation by default because this is the default
181+
behavior of the ``SslStream`` class in both the
182+
`{+framework+} <https://learn.microsoft.com/en-us/dotnet/api/system.net.security.sslstream.authenticateasclient?view=netframework-{+framework-version+}#System_Net_Security_SslStream_AuthenticateAsClient_System_String_>`__
183+
and the `.NET standard. <https://learn.microsoft.com/en-us/dotnet/api/system.net.security.sslstream.authenticateasclient?view=netstandard-{+standard-version+}#System_Net_Security_SslStream_AuthenticateAsClient_System_String_>`__
184+
185+
Revocation Checking by Operating System
186+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187+
188+
The {+driver-short+} supports the following revocation-checking mechanisms differently on
189+
Windows, macOS, and Linux:
190+
191+
- :wikipedia:`Online Certificate Status Protocol (OCSP) <Online_Certificate_Status_Protocol>`,
192+
a common mechanism for checking revocation
193+
- :wikipedia:`OCSP stapling <OCSP_stapling>`, a mechanism in which the server
194+
includes a time-stamped OCSP response to the client along with the certificate
195+
- :wikipedia:`Certificate revocation lists (CRLs), <Certificate_revocation_list>`,
196+
an alternative to OCSP
197+
198+
Windows
199+
```````
200+
201+
On Windows, the {+driver-short+} supports OCSP, OCSP stapling, and CRLs without OCSP,
202+
in both the .NET Framework and .NET Core.
203+
204+
.. warning::
205+
206+
On Windows, the {+driver-short+} will report a "hard fail" and cancel the TLS
207+
handshake if the OCSP responder is unavailable. Other operating systems and drivers
208+
will report a "soft fail" and continue connecting.
209+
210+
macOS
211+
`````
212+
213+
On macOS, the {+driver-short+} supports OCSP and OCSP stapling.
214+
215+
Beginning with .NET Core 2.0, the driver does **not** support CRLs without OCSP.
216+
217+
Linux
218+
`````
219+
220+
On Linux, the {+driver-short+} supports OCSP, OCSP stapling, and CRLs without OCSP.
221+
222+
API Documentation
223+
-----------------
224+
225+
To learn more about any of the connection options discussed in this
226+
guide, see the following API documentation:
227+
228+
- `MongoClientSettings <{+api-root+}/T_MongoDB_Driver_MongoClientSettings.htm>`__

0 commit comments

Comments
 (0)