Swift Driver TLS/SSL Guide
This guide covers the installation requirements and configuration options for connecting to MongoDB over TLS/SSL in the driver. See the server documentation to configure MongoDB to use TLS/SSL.
The driver relies on the the TLS/SSL library installed on your system for making secure connections to the database.
- On macOS, the driver depends on SecureTransport, the native TLS library for macOS, so no additional installation is required.
- On Linux, the driver depends on OpenSSL, which is usually bundled with your OS but may require specific installation. The driver also supports LibreSSL through the use of OpenSSL compatibility checks.
Ensuring TLS 1.1+
Industry best practices recommend, and some regulations require, the use of TLS 1.1 or newer. Though no application changes are required for the driver to make use of the newest protocols, some operating systems or versions may not provide a TLS library version new enough to support them.
Users of Linux or other non-macOS Unix can check their OpenSSL version like this:
$ openssl version
If the version number is less than 1.0.1, support for TLS 1.1 or newer is not available. Contact your operating system vendor for a solution, upgrade to a newer distribution, or manually upgrade your installation of OpenSSL.
macOS 10.13 (High Sierra) and newer support TLS 1.1+.
To require that connections to MongoDB made by the driver use TLS/SSL, specify
tls: true in the
MongoClientOptions passed to a
let client = try MongoClient("mongodb://example.com", using: elg, options: MongoClientOptions(tls: true))
tls=true can be specified in the MongoDB Connection String passed to the initializer:
let client = try MongoClient("mongodb://example.com/?tls=true", using: elg)
Note: Specifying any
tls-prefixed option in the connection string or
MongoClientOptions will require all connections made by the driver to use TLS/SSL.
Specifying a CA File
The driver can be configured to use a specific set of CA certificates. This is most often used with “self-signed” server certificates.
A path to a file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection can be specified via the
tlsCAFile option on
let client = try MongoClient("mongodb://example.com", using: elg, options: MongoClientOptions(tlsCAFile: URL(string: "/path/to/ca.pem")))
Alternatively, the path can be specified via the
tlsCAFile option in the MongoDB Connection String passed to the client’s initializer:
let caFile = "/path/to/ca.pem".addingPercentEncoding(withAllowedCharacters: .urlHostAllowed)! let client = try MongoClient("mongodb://example.com/?tlsCAFile=\(caFile)", using: elg)
Specifying a Client Certificate or Private Key File
The driver can be configured to present the client certificate file or the client private key file via the
tlsCertificateKeyFile option on
let client = try MongoClient("mongodb://example.com", using: elg, options: MongoClientOptions(tlsCertificateKeyFile: URL(string: "/path/to/cert.pem")))
If the private key is password protected, a password can be supplied via
let client = try MongoClient( "mongodb://example.com", using: elg, options: MongoClientOptions(tlsCertificateKeyFile: URL(string: "/path/to/cert.pem"), tlsCertificateKeyFilePassword: <password>) )
Alternatively, these options can be set via the
tlsCertificateKeyFilePassword options in the MongoDB Connection String passed into the initializer:
let certificatePath = "/path/to/cert.pem".addingPercentEncoding(withAllowedCharacters: .urlHostAllowed)! let password = "not a secure password".addingPercentEncoding(withAllowedCharacters: .urlHostAllowed)! let client = try MongoClient( "mongodb://example.com/?tlsCertificateKeyFile=\(certificatePath)&tlsCertificateKeyFilePassword=\(password)", using: elg )
Note: In both cases, if both a client certificate and a client private key are needed, the files should be concatenated into a single file which is specified by
Server Certificate Validation
The driver will automatically verify the validity of the server certificate by ensuring that it was issued by the configured Certificate Authority, its SAN or CN match the hostname provided in the connection string, and it has not expired.
To override this behavior, it is possible to disable parts or all of it via the following options in the
MongoClientOptions or connection string used to create the
tlsAllowInvalidHostnames: disables hostname validation
tlsDisableOCSPEndpointCheck: disables OCSP endpoint revocation checking. This does not disable verifying OCSP responses stapled to a server’s certificate
tlsDisableCertificateRevocationCheck: disables revocation checking entirely, including via OCSP stapled responses or CRLs.
tlsAllowInvalidCertificates: completely disables server certificate verification and allows any certificate to be used.
By default, all of these options are set to false.
It is not recommended to change these defaults as it exposes the client to on-path-attackers (when
tlsAllowInvalidHostnames is set), invalid certificates (when
tlsAllowInvalidCertificates is set), or potentially
revoked certificates (when
tlsDisableCertificateRevocationCheck are set).
tlsDisableOCSPEndpointCheck have no effect on macOS.
OCSP on Linux/OpenSSL
The Online Certificate Status Protocol (OCSP) (see RFC 6960) is fully supported when using OpenSSL 1.0.1+.
OCSP on macOS
The Online Certificate Status Protocol (OCSP) (see RFC 6960) is partially supported with the following notes:
The Must-Staple extension (see RFC 7633) is ignored. Connection may continue if a Must-Staple certificate is presented with no stapled response (unless the client receives a revoked response from an OCSP responder).
Connection will continue if a Must-Staple certificate is presented without a stapled response and the OCSP responder is down.