1MONGOC_CONFIGURING_TLS(3) libmongoc MONGOC_CONFIGURING_TLS(3)
2
6 Enable TLS by including tls=true in the URI.
7 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017/");
9 mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
10 mongoc_client_t *client = mongoc_client_new_from_uri (uri);
12 The following URI options may be used to further configure TLS:
14 ┌────────────────────┬─────────────────────┬─────────────────────┐
16 │Constant │ Key │ Description │
17 ├────────────────────┼─────────────────────┼─────────────────────┤
18 │MONGOC_URI_TLS │ tls │ {true|false}, indi‐ │
19 │ │ │ cating if TLS must │
20 │ │ │ be used. │
21 ├────────────────────┼─────────────────────┼─────────────────────┤
22 │MONGOC_URI_TLSCER‐ │ tlscertificatekey‐ │ Path to PEM format‐ │
23 │TIFICATEKEYFILE │ file │ ted Private Key, │
24 │ │ │ with its Public │
25 │ │ │ Certificate con‐ │
26 │ │ │ catenated at the │
27 │ │ │ end. │
28 ├────────────────────┼─────────────────────┼─────────────────────┤
29 │MONGOC_URI_TLSCER‐ │ tlscertificatekey‐ │ The password, if │
30 │TIFICATEKEY‐ │ password │ any, to use to un‐ │
31 │FILEPASSWORD │ │ lock encrypted Pri‐ │
32 │ │ │ vate Key. │
33 ├────────────────────┼─────────────────────┼─────────────────────┤
34 │MON‐ │ tlscafile │ One, or a bundle │
35 │GOC_URI_TLSCAFILE │ │ of, Certificate Au‐ │
36 │ │ │ thorities whom │
37 │ │ │ should be consid‐ │
38 │ │ │ ered to be trusted. │
39 ├────────────────────┼─────────────────────┼─────────────────────┤
40 │MONGOC_URI_TLSAL‐ │ tlsallowinvalidcer‐ │ Accept and ignore │
41 │LOWINVALIDCERTIFI‐ │ tificates │ certificate verifi‐ │
42 │CATES │ │ cation errors (e.g. │
43 │ │ │ untrusted issuer, │
44 │ │ │ expired, etc.) │
45 ├────────────────────┼─────────────────────┼─────────────────────┤
46 │MONGOC_URI_TLSAL‐ │ tlsallowinvalid‐ │ Ignore hostname │
47 │LOWINVALIDHOSTNAMES │ hostnames │ verification of the │
48 │ │ │ certificate (e.g. │
49 │ │ │ Man In The Middle, │
50 │ │ │ using valid cer‐ │
51 │ │ │ tificate, but is‐ │
52 │ │ │ sued for another │
53 │ │ │ hostname) │
54 ├────────────────────┼─────────────────────┼─────────────────────┤
55 │MONGOC_URI_TLSINSE‐ │ tlsinsecure │ {true|false}, indi‐ │
56 │CURE │ │ cating if insecure │
57 │ │ │ TLS options should │
58 │ │ │ be used. Currently │
59 │ │ │ this implies MON‐ │
60 │ │ │ GOC_URI_TLSALLOWIN‐ │
61 │ │ │ VALIDCERTIFICATES │
62 │ │ │ and MONGOC_URI_TL‐ │
63 │ │ │ SALLOWINVALIDHOST‐ │
64 │ │ │ NAMES. │
65 └────────────────────┴─────────────────────┴─────────────────────┘
66 │MONGOC_URI_TLSDIS‐ │ tlsdisablecertifi‐ │ {true|false}, indi‐ │
68 │ABLECERTIFICATERE‐ │ caterevocationcheck │ cates if revocation │
69 │VOCATIONCHECK │ │ checking (CRL / │
70 │ │ │ OCSP) should be │
71 │ │ │ disabled. │
72 ├────────────────────┼─────────────────────┼─────────────────────┤
73 │MONGOC_URI_TLSDIS‐ │ tlsdisableocspend‐ │ {true|false}, indi‐ │
74 │ABLEOCSPEND‐ │ pointcheck │ cates if OCSP re‐ │
75 │POINTCHECK │ │ sponder endpoints │
76 │ │ │ should not be re‐ │
77 │ │ │ quested when an │
78 │ │ │ OCSP response is │
79 │ │ │ not stapled. │
80 └────────────────────┴─────────────────────┴─────────────────────┘
81
83 Alternatively, the mongoc_ssl_opt_t struct may be used to configure TLS
84 with mongoc_client_set_ssl_opts() or mongoc_client_pool_set_ssl_opts().
85 Most of the configurable options can be set using the Connection String
86 URI.
87 ┌───────────────────────┬──────────────────────────┐
89 │mongoc_ssl_opt_t key │ URI key │
90 ├───────────────────────┼──────────────────────────┤
91 │pem_file │ tlsClientCertificateKey‐ │
92 │ │ File │
93 ├───────────────────────┼──────────────────────────┤
94 │pem_pwd │ tlsClientCertificateKey‐ │
95 │ │ Password │
96 ├───────────────────────┼──────────────────────────┤
97 │ca_file │ tlsCAFile │
98 ├───────────────────────┼──────────────────────────┤
99 │weak_cert_validation │ tlsAllowInvalidCertifi‐ │
100 │ │ cates │
101 ├───────────────────────┼──────────────────────────┤
102 │allow_invalid_hostname │ tlsAllowInvalidHostnames │
103 └───────────────────────┴──────────────────────────┘
104 The only exclusions are crl_file and ca_dir. Those may only be set with
106 mongoc_ssl_opt_t.
107
109 When MongoDB is started with TLS enabled, it will by default require
110 the client to provide a client certificate issued by a certificate au‐
111 thority specified by --tlsCAFile, or an authority trusted by the native
112 certificate store in use on the server.
113 To provide the client certificate, set the tlsCertificateKeyFile in the
115 URI to a PEM armored certificate file.
116 mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017/");
118 mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
119 mongoc_uri_set_option_as_utf8 (uri, MONGOC_URI_TLSCERTIFICATEKEYFILE, "/path/to/client-certificate.pem");
120 mongoc_client_t *client = mongoc_client_new_from_uri (uri);
122
124 The MongoDB C Driver will automatically verify the validity of the
125 server certificate, such as issued by configured Certificate Authority,
126 hostname validation, and expiration.
127 To overwrite this behavior, it is possible to disable hostname valida‐
129 tion, OCSP endpoint revocation checking, revocation checking entirely,
130 and allow invalid certificates.
131 This behavior is controlled using the tlsAllowInvalidHostnames, tlsDis‐
133 ableOCSPEndpointCheck, tlsDisableCertificateRevocationCheck, and tlsAl‐
134 lowInvalidCertificates options respectively. By default, all are set to
135 false.
136 It is not recommended to change these defaults as it exposes the client
138 to Man In The Middle attacks (when tlsAllowInvalidHostnames is set),
139 invalid certificates (when tlsAllowInvalidCertificates is set), or po‐
140 tentially revoked certificates (when tlsDisableOCSPEndpointCheck or
141 tlsDisableCertificateRevocationCheck are set).
142
144 By default, libmongoc will attempt to find a supported TLS library and
145 enable TLS support. This is controlled by the cmake flag ENABLE_SSL,
146 which is set to AUTO by default. Valid values are:
147 • AUTO the default behavior. Link to the system's native TLS library,
149 or attempt to find OpenSSL.
150 • DARWIN link to Secure Transport, the native TLS library on macOS.
152 • WINDOWS link to Secure Channel, the native TLS library on Windows.
154 • OPENSSL link to OpenSSL (libssl). An optional install path may be
156 specified with OPENSSL_ROOT.
157 • LIBRESSL link to LibreSSL's libtls. (LibreSSL's compatible libssl may
159 be linked to by setting OPENSSL).
160 • OFF disable TLS support.
162 OpenSSL
164 The MongoDB C Driver uses OpenSSL, if available, on Linux and Unix
165 platforms (besides macOS). Industry best practices and some regulations
166 require the use of TLS 1.1 or newer, which requires at least OpenSSL
167 1.0.1. Check your OpenSSL version like so:
168 $ openssl version
170 Ensure your system's OpenSSL is a recent version (at least 1.0.1), or
172 install a recent version in a non-system path and build against it
173 with:
174 cmake -DOPENSSL_ROOT_DIR=/absolute/path/to/openssl
176 When compiled against OpenSSL, the driver will attempt to load the sys‐
178 tem default certificate store, as configured by the distribution. That
179 can be overridden by setting the tlsCAFile URI option or with the
180 fields ca_file and ca_dir in the mongoc_ssl_opt_t.
181 The Online Certificate Status Protocol (OCSP) (see RFC 6960) is fully
183 supported when using OpenSSL 1.0.1+ with the following notes:
184 • When a crl_file is set with mongoc_ssl_opt_t, and the crl_file re‐
186 vokes the server's certificate, the certificate is considered revoked
187 (even if the certificate has a valid stapled OCSP response)
188 LibreSSL / libtls
190 The MongoDB C Driver supports LibreSSL through the use of OpenSSL com‐
191 patibility checks when configured to compile against openssl. It also
192 supports the new libtls library when configured to build against li‐
193 bressl.
194 When compiled against the Windows native libraries, the crl_file option
196 of a mongoc_ssl_opt_t is not supported, and will issue an error if
197 used.
198 Setting tlsDisableOCSPEndpointCheck and tlsDisableCertificateRevoca‐
200 tionCheck has no effect.
201 The Online Certificate Status Protocol (OCSP) (see RFC 6960) is par‐
203 tially supported with the following notes:
204 • The Must-Staple extension (see RFC 7633) is ignored. Connection may
206 continue if a Must-Staple certificate is presented with no stapled
207 response (unless the client receives a revoked response from an OCSP
208 responder).
209 • Connection will continue if a Must-Staple certificate is presented
211 without a stapled response and the OCSP responder is down.
212 Native TLS Support on Windows (Secure Channel)
214 The MongoDB C Driver supports the Windows native TLS library (Secure
215 Channel, or SChannel), and its native crypto library (Cryptography API:
216 Next Generation, or CNG).
217 When compiled against the Windows native libraries, the ca_dir option
219 of a mongoc_ssl_opt_t is not supported, and will issue an error if
220 used.
221 Encrypted PEM files (e.g., setting tlsCertificateKeyPassword) are also
223 not supported, and will result in error when attempting to load them.
224 When tlsCAFile is set, the driver will only allow server certificates
226 issued by the authority (or authorities) provided. When no tlsCAFile is
227 set, the driver will look up the Certificate Authority using the System
228 Local Machine Root certificate store to confirm the provided certifi‐
229 cate.
230 When crl_file is set with mongoc_ssl_opt_t, the driver will import the
232 revocation list to the System Local Machine Root certificate store.
233 Setting tlsDisableOCSPEndpointCheck has no effect.
235 The Online Certificate Status Protocol (OCSP) (see RFC 6960) is par‐
237 tially supported with the following notes:
238 • The Must-Staple extension (see RFC 7633) is ignored. Connection may
240 continue if a Must-Staple certificate is presented with no stapled
241 response (unless the client receives a revoked response from an OCSP
242 responder).
243 • When a crl_file is set with mongoc_ssl_opt_t, and the crl_file re‐
245 vokes the server's certificate, the OCSP response takes precedence.
246 E.g. if the server presents a certificate with a valid stapled OCSP
247 response, the certificate is considered valid even if the crl_file
248 marks it as revoked.
249 • Connection will continue if a Must-Staple certificate is presented
251 without a stapled response and the OCSP responder is down.
252 Native TLS Support on macOS / Darwin (Secure Transport)
254 The MongoDB C Driver supports the Darwin (OS X, macOS, iOS, etc.) na‐
255 tive TLS library (Secure Transport), and its native crypto library
256 (Common Crypto, or CC).
257 When compiled against Secure Transport, the ca_dir and crl_file options
259 of a mongoc_ssl_opt_t are not supported. An error is issued if either
260 are used.
261 When tlsCAFile is set, the driver will only allow server certificates
263 issued by the authority (or authorities) provided. When no tlsCAFile is
264 set, the driver will use the Certificate Authorities in the currently
265 unlocked keychains.
266 Setting tlsDisableOCSPEndpointCheck and tlsDisableCertificateRevoca‐
268 tionCheck has no effect.
269 The Online Certificate Status Protocol (OCSP) (see RFC 6960) is par‐
271 tially supported with the following notes.
272 • The Must-Staple extension (see RFC 7633) is ignored. Connection may
274 continue if a Must-Staple certificate is presented with no stapled
275 response (unless the client receives a revoked response from an OCSP
276 responder).
277 • Connection will continue if a Must-Staple certificate is presented
279 without a stapled response and the OCSP responder is down.
280
282 MongoDB, Inc
283
285 2017-present, MongoDB, Inc
2861.25.1 Nov 08, 2023 MONGOC_CONFIGURING_TLS(3)