Docs Home → Develop Applications → MongoDB Drivers → C#/.NET
Enable TLS on a Connection
On this page
Overview
In this guide, you can learn how to connect to MongoDB instances with the TLS/SSL security protocol using the underlying TLS/SSL support in the .NET framework. To configure your connection to use TLS/SSL, enable the TLS/SSL settings in either the connection string or MongoClientSettings.
Enable TLS
You can enable TLS for the connection to your MongoDB instance
in two different ways: using a property on a MongoClientSettings object or
through a parameter in your connection string.
Configure a Client Certificate
You can configure your X.509 certificate using MongoClientSettings. The following
code sample creates a new X.509 certificate object using the certificate file named
client.p12, which is protected by the password mySuperSecretPassword. The code
then adds this certificate to the SslSettings.ClientCertificates array in
MongoClientSettings.
var cert = new X509Certificate2("client.p12", "mySuperSecretPassword"); var settings = new MongoClientSettings { SslSettings = new SslSettings { ClientCertificates = new[] { cert } }, UseTls = true };
Important
When loading a certificate with a password, the certificate object must contain a private key. If it doesn't, your certificate will not be passed to the server.
Allow Insecure TLS
When TLS is enabled, the .NET/C# Driver automatically verifies the certificate that the server presents. When testing your code, you can disable certificate verification. This is known as insecure TLS.
When using insecure TLS, the only requirement is that the server present an X.509 certificate. The driver will accept 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.
You can allow insecure TLS in two different ways: using a property on a
MongoClientSettings object or through a parameter in your connection string.
Warning
Always set this option to false in production. For security reasons, it's
important that the server certificate is properly validated.
Check Certificate Revocation
When an X.509 certificate should no longer be trusted--for example, if its private key has been compromised--the certificate authority will revoke the certificate.
By default, the .NET/C# Driver doesn't check whether a server's certificate has been
revoked before it connects. You can enable revocation checking using either
MongoClientSettings or the connection string.
Note
The .NET/C# Driver doesn't check revocation by default because this is the default
behavior of the SslStream class in both the
.NET framework
and the .NET standard.
Revocation Checking by Operating System
The .NET/C# Driver supports the following revocation-checking mechanisms differently on Windows, macOS, and Linux:
Online Certificate Status Protocol (OCSP), a common mechanism for checking revocation
OCSP stapling, a mechanism in which the server includes a time-stamped OCSP response to the client along with the certificate
Certificate revocation lists (CRLs),, an alternative to OCSP
Windows
On Windows, the .NET/C# Driver supports OCSP, OCSP stapling, and CRLs without OCSP, in both the .NET Framework and .NET Core.
Warning
On Windows, the .NET/C# Driver will report a "hard fail" and cancel the TLS handshake if the OCSP responder is unavailable. Other operating systems and drivers will report a "soft fail" and continue connecting.
macOS
On macOS, the .NET/C# Driver supports OCSP and OCSP stapling.
Beginning with .NET Core 2.0, the driver does not support CRLs without OCSP.
Linux
On Linux, the .NET/C# Driver supports OCSP, OCSP stapling, and CRLs without OCSP.
API Documentation
To learn more about any of the connection options discussed in this guide, see the following API documentation: