In this guide, you can learn how to use the TLS protocol to secure your connection to a MongoDB deployment.
When you enable TLS for a connection, the C driver performs the following actions:
Uses TLS to connect to the MongoDB deployment
Verifies the deployment's certificate
Ensures that the certificate certifies the deployment
To learn how to configure your MongoDB deployment for TLS, see the TLS configuration guide in the MongoDB Server manual.
NoteA full description of TLS/SSL, PKI (Public Key Infrastructure) certificates, and Certificate Authorities (CAs) is beyond the scope of this document. This page assumes prior knowledge of TLS/SSL and access to valid certificates.
You can enable TLS on a connection to your MongoDB instance in the following ways:
Setting the tls parameter in your connection string
Using the mongoc_uri_set_option_as_bool() function to set the MONGOC_URI_TLS connection option to true
mongoc_client_t *client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname>/?tls=true");mongoc_client_destroy (client);mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017"); mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);mongoc_client_t *client = mongoc_client_new_from_uri (uri);mongoc_client_destroy (client);mongoc_uri_destroy (uri);If your connection string includes the +srv modification, which specifies the SRV connection format, TLS is enabled on your connection by default.
To learn more about the SRV connection format, see SRV Connection Format in the MongoDB Server documentation.
When you connect to a MongoDB deployment with TLS enabled, the deployment will by default require the client to provide a client certificate issued by a certificate authority, or an authority trusted by the native certificate store in use on the server.
You can provide the client certificate in the following ways:
Setting the tlsCertificateKeyFile parameter in your connection string to a .pem file containing the root certificate chain
Using the mongoc_uri_set_option_as_utf8() function to set the MONGOC_URI_TLSCERTIFICATEKEYFILE option to a .pem file containing the root certificate chain
mongoc_client_t *client = mongoc_client_new ("mongodb+srv://<db_username>:<db_password>@<hostname>/?tls=true&tlscertificatekeyfile=/path/to/certs/client-certificate.pem");mongoc_client_destroy (client);mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017"); mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);mongoc_uri_set_option_as_utf8 (uri, MONGOC_URI_TLSCERTIFICATEKEYFILE, "/path/to/client-certificate.pem"); mongoc_client_t *client = mongoc_client_new_from_uri (uri);mongoc_client_destroy (client);mongoc_uri_destroy (uri);The MongoDB C Driver will automatically verify the validity of a server certificate issued by the configured Certificate Authority. The driver also performs hostname validation and revocation checking.
To overwrite this behavior, it is possible to disable hostname validation, OCSP endpoint revocation checking, all revocation checking, and allow invalid certificates.
This behavior is controlled using the tlsAllowInvalidHostnames, tlsDisableOCSPEndpointCheck, tlsDisableCertificateRevocationCheck, and tlsAllowInvalidCertificates options. By default, all are set to false.
It is not recommended to change these defaults, since you might expose your client to the following security risks:
Man In The Middle attacks , when tlsAllowInvalidHostnames is set
Invalid certificates, when tlsAllowInvalidCertificates is set
Potentially revoked certificates, when tlsDisableOCSPEndpointCheck or tlsDisableCertificateRevocationCheck are set
By default, libmongoc will attempt to find a supported TLS library and enable TLS support. This is controlled by the cmake flag ENABLE_SSL, which is set to AUTO by default. This flag accepts the following values:
AUTO: Links to the system's native TLS library, or attempts to find OpenSSL. This is the default value.
OPENSSL: Links to OpenSSL (libssl). An optional install path may be specified with OPENSSL_ROOT.
WINDOWS: Links to Secure Channel, the native TLS library on Windows.
DARWIN: Links to Secure Transport, the native TLS library on macOS.
OFF: Disables TLS support.
The MongoDB C Driver uses OpenSSL on Linux and Unix platforms (besides macOS). Industry best practices and some regulations require the use of TLS 1.1 or newer, which requires at least OpenSSL 1.0.1. Use the following command to check your OpenSSL version:
Ensure your system's OpenSSL is a recent version (at least 1.0.1), or use the following command to install a recent version in a non-system path and build against it:
cmake -DOPENSSL_ROOT_DIR=/absolute/path/to/opensslWhen compiled against OpenSSL, the driver will attempt to load the system default certificate store, as configured by the distribution. That can be overridden by setting the tlsCAFile URI option or with the fields ca_file and ca_dir in the mongoc_ssl_opt_t.
The Online Certificate Status Protocol (OCSP) is fully supported when using OpenSSL 1.0.1+. However, when a crl_file is set with mongoc_ssl_opt_t and the crl_file revokes the server's certificate, the certificate is considered revoked, even if the certificate has a valid stapled OCSP response.
For more information about OCSP, see RFC 6960.
The MongoDB C Driver supports the Windows native TLS library (Secure Channel, or SChannel) and its native crypto library (Cryptography API: Next Generation, or CNG).
When compiled against the Windows native libraries, the ca_dir option of a mongoc_ssl_opt_t is not supported and issues an error if used. Encrypted PEM files, set by using the tlsCertificateKeyPassword URI option, are also not supported and issue errors when you attempt to load them.
The tlsCertificateKeyFile URI option can refer to a certificate encoded in either the PKCS#8 or PKCS#1 format. Starting with version 2.1.0 of the C driver, the driver imports the private key as a persistent key to support modern signature algorithms. In earlier versions, the driver imported the key as ephemeral. To learn more about managing imported keys, see Managing Imported Keys.
When tlsCAFile is set, the driver imports the Certificate Authority file to the System Local Machine Root certificate store. When no tlsCAFile is set, the driver looks up the Certificate Authority file using the System Local Machine Root certificate store to confirm the provided certificate.
When crl_file is set with mongoc_ssl_opt_t , the driver imports the revocation list to the System Local Machine Root certificate store. Setting tlsDisableOCSPEndpointCheck has no effect.
The Online Certificate Status Protocol (OCSP) is partially supported with the following notes:
Must-Staple extension (see RFC 7633 ) is ignored.
Connection will continue if a Must-Staple certificate is presented without a stapled response and the OCSP responder is down.
Connection will not continue if the client receives a revoked response from an OCSP responder.
When a crl_file is set with mongoc_ssl_opt_t , and the crl_file revokes the server's certificate, the OCSP response takes precedence. For example, if the server presents a certificate with a valid stapled OCSP response, the certificate is considered valid even if the crl_file marks it as revoked.
For more information about OCSP, see RFC 6960.
The C Driver imports PKCS#8 keys into the CNG KSP: Microsoft Software Key Storage Provider and imports PKCS#1 keys into the legacy CryptoAPI CSP: Microsoft Enhanced Cryptographic Provider v1.0. To learn more about key imports, see Key Storage and Retrieval in the Microsoft documentation.
After you import keys, you might need to compute the key name and provider, view the key, or delete the key. The following PowerShell code computes the key name and providers:
$cert = "client.pem"# Compute the SHA256 fingerprint:$fingerprint = (openssl x509 -in $cert -noout -fingerprint -sha256) -replace 'SHA256 Fingerprint=', '' -replace ':', ''if (Select-String -Path $cert -Pattern '-----BEGIN RSA PRIVATE KEY-----' -Quiet) { # Key name for PKCS#1 key: $key_name = "libmongoc-$fingerprint-pkcs1" $csp = "Microsoft Enhanced Cryptographic Provider v1.0"} elseif (Select-String -Path $cert -Pattern '-----BEGIN PRIVATE KEY-----' -Quiet) { # Key name for PKCS#8 key: $key_name = "libmongoc-$fingerprint-pkcs8" $csp = "Microsoft Software Key Storage Provider"} else { Write-Output "Unexpected PEM format for $cert"}The following PowerShell code displays details about the key:
certutil -user -csp $csp -key $key_nameThe following PowerShell code deletes the key:
certutil -user -csp $csp -key $key_nameThe MongoDB C Driver supports both the Darwin native TLS library and Common Crypto, its native crypto library.
When compiled against Secure Transport, the ca_dir and crl_file options of a mongoc_ssl_opt_t are not supported. An error is issued if either are used.
When tlsCAFile is set, the driver will only allow server certificates issued by the authority (or authorities) provided. When no tlsCAFile is set, the driver will use the Certificate Authorities in the unlocked keychains.
Setting tlsDisableOCSPEndpointCheck and tlsDisableCertificateRevocationCheck has no effect when compiling against secure transport.
The Online Certificate Status Protocol (OCSP) is partially supported with the following notes.
Must-Staple extension (see RFC 7633 ) is ignored
Connection will continue if a Must-Staple certificate is presented without a stapled response and the OCSP responder is down
Connection will not continue if the client receives a revoked response from an OCSP responder
For more information about OCSP, see RFC 6960.
For more information about the objects and functions mentioned in this guide, see the following API documentation:
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4