1MONGOC_CONFIGURING_TLS(3)          libmongoc         MONGOC_CONFIGURING_TLS(3)
2
3
4

NAME

6       mongoc_configuring_tls - Configuring TLS
7

CONFIGURATION WITH URI OPTIONS

9       Enable TLS by including tls=true in the URI.
10
11          mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017/");
12          mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
13
14          mongoc_client_t *client = mongoc_client_new_from_uri (uri);
15
16       The following URI options may be used to further configure TLS:
17
18          ┌────────────────────┬─────────────────────┬─────────────────────┐
19          │Constant            │ Key                 │ Description         │
20          ├────────────────────┼─────────────────────┼─────────────────────┤
21          │MONGOC_URI_TLS      │ tls                 │ {true|false}, indi‐ │
22          │                    │                     │ cating if TLS  must │
23          │                    │                     │ be used.            │
24          ├────────────────────┼─────────────────────┼─────────────────────┤
25          │MONGOC_URI_TLSCER‐  │ tlscertificatekey‐  │ Path to PEM format‐ │
26          │TIFICATEKEYFILE     │ file                │ ted  Private   Key, │
27          │                    │                     │ with   its   Public │
28          │                    │                     │ Certificate    con‐ │
29          │                    │                     │ catenated   at  the │
30          │                    │                     │ end.                │
31          ├────────────────────┼─────────────────────┼─────────────────────┤
32          │MONGOC_URI_TLSCER‐  │ tlscertificatekey‐  │ The   password,  if │
33          │TIFICATEKEY‐        │ password            │ any, to use to  un‐ │
34          │FILEPASSWORD        │                     │ lock encrypted Pri‐ │
35          │                    │                     │ vate Key.           │
36          ├────────────────────┼─────────────────────┼─────────────────────┤
37          │MON‐                │ tlscafile           │ One,  or  a  bundle │
38          │GOC_URI_TLSCAFILE   │                     │ of, Certificate Au‐ │
39          │                    │                     │ thorities      whom │
40          │                    │                     │ should  be  consid‐ │
41          │                    │                     │ ered to be trusted. │
42          ├────────────────────┼─────────────────────┼─────────────────────┤
43          │MONGOC_URI_TLSAL‐   │ tlsallowinvalidcer‐ │ Accept  and  ignore │
44          │LOWINVALIDCERTIFI‐  │ tificates           │ certificate verifi‐ │
45          │CATES               │                     │ cation errors (e.g. │
46          │                    │                     │ untrusted   issuer, │
47          │                    │                     │ expired, etc.)      │
48          ├────────────────────┼─────────────────────┼─────────────────────┤
49          │MONGOC_URI_TLSAL‐   │ tlsallowinvalid‐    │ Ignore     hostname │
50          │LOWINVALIDHOSTNAMES │ hostnames           │ verification of the │
51          │                    │                     │ certificate   (e.g. │
52          │                    │                     │ Man  In The Middle, │
53          │                    │                     │ using  valid   cer‐ │
54          │                    │                     │ tificate,  but  is‐ │
55          │                    │                     │ sued  for   another │
56          │                    │                     │ hostname)           │
57          └────────────────────┴─────────────────────┴─────────────────────┘
58
59
60
61
62
63
64
65
66
67          │MONGOC_URI_TLSINSE‐ │ tlsinsecure         │ {true|false}, indi‐ │
68          │CURE                │                     │ cating  if insecure │
69          │                    │                     │ TLS options  should │
70          │                    │                     │ be  used. Currently │
71          │                    │                     │ this  implies  MON‐ │
72          │                    │                     │ GOC_URI_TLSALLOWIN‐ │
73          │                    │                     │ VALIDCERTIFICATES   │
74          │                    │                     │ and  MONGOC_URI_TL‐ │
75          │                    │                     │ SALLOWINVALIDHOST‐  │
76          │                    │                     │ NAMES.              │
77          ├────────────────────┼─────────────────────┼─────────────────────┤
78          │MONGOC_URI_TLSDIS‐  │ tlsdisablecertifi‐  │ {true|false}, indi‐ │
79          │ABLECERTIFICATERE‐  │ caterevocationcheck │ cates if revocation │
80          │VOCATIONCHECK       │                     │ checking   (CRL   / │
81          │                    │                     │ OCSP)   should   be │
82          │                    │                     │ disabled.           │
83          ├────────────────────┼─────────────────────┼─────────────────────┤
84          │MONGOC_URI_TLSDIS‐  │ tlsdisableocspend‐  │ {true|false}, indi‐ │
85          │ABLEOCSPEND‐        │ pointcheck          │ cates if  OCSP  re‐ │
86          │POINTCHECK          │                     │ sponder   endpoints │
87          │                    │                     │ should not  be  re‐ │
88          │                    │                     │ quested   when   an │
89          │                    │                     │ OCSP  response   is │
90          │                    │                     │ not stapled.        │
91          └────────────────────┴─────────────────────┴─────────────────────┘
92

CONFIGURATION WITH MONGOC_SSL_OPT_T

94       Alternatively, the mongoc_ssl_opt_t struct may be used to configure TLS
95       with mongoc_client_set_ssl_opts() or mongoc_client_pool_set_ssl_opts().
96       Most of the configurable options can be set using the Connection String
97       URI.
98
99                 ┌───────────────────────┬──────────────────────────┐
100mongoc_ssl_opt_t key   URI key                  
101                 ├───────────────────────┼──────────────────────────┤
102                 │pem_file               │ tlsClientCertificateKey‐ │
103                 │                       │ File                     │
104                 ├───────────────────────┼──────────────────────────┤
105                 │pem_pwd                │ tlsClientCertificateKey‐ │
106                 │                       │ Password                 │
107                 ├───────────────────────┼──────────────────────────┤
108                 │ca_file                │ tlsCAFile                │
109                 ├───────────────────────┼──────────────────────────┤
110                 │weak_cert_validation   │ tlsAllowInvalidCertifi‐  │
111                 │                       │ cates                    │
112                 ├───────────────────────┼──────────────────────────┤
113                 │allow_invalid_hostname │ tlsAllowInvalidHostnames │
114                 └───────────────────────┴──────────────────────────┘
115
116       The only exclusions are crl_file and ca_dir. Those may only be set with
117       mongoc_ssl_opt_t.
118

CLIENT AUTHENTICATION

120       When MongoDB is started with TLS enabled, it will  by  default  require
121       the  client to provide a client certificate issued by a certificate au‐
122       thority specified by --tlsCAFile, or an authority trusted by the native
123       certificate store in use on the server.
124
125       To provide the client certificate, set the tlsCertificateKeyFile in the
126       URI to a PEM armored certificate file.
127
128          mongoc_uri_t *uri = mongoc_uri_new ("mongodb://localhost:27017/");
129          mongoc_uri_set_option_as_bool (uri, MONGOC_URI_TLS, true);
130          mongoc_uri_set_option_as_utf8 (uri, MONGOC_URI_TLSCERTIFICATEKEYFILE, "/path/to/client-certificate.pem");
131
132          mongoc_client_t *client = mongoc_client_new_from_uri (uri);
133

SERVER CERTIFICATE VERIFICATION

135       The MongoDB C Driver will automatically  verify  the  validity  of  the
136       server certificate, such as issued by configured Certificate Authority,
137       hostname validation, and expiration.
138
139       To overwrite this behavior, it is possible to disable hostname  valida‐
140       tion,  OCSP endpoint revocation checking, revocation checking entirely,
141       and allow invalid certificates.
142
143       This behavior is controlled using the tlsAllowInvalidHostnames, tlsDis‐
144       ableOCSPEndpointCheck, tlsDisableCertificateRevocationCheck, and tlsAl‐
145       lowInvalidCertificates options respectively. By default, all are set to
146       false.
147
148       It is not recommended to change these defaults as it exposes the client
149       to Man In The Middle attacks (when  tlsAllowInvalidHostnames  is  set),
150       invalid  certificates (when tlsAllowInvalidCertificates is set), or po‐
151       tentially revoked  certificates  (when  tlsDisableOCSPEndpointCheck  or
152       tlsDisableCertificateRevocationCheck are set).
153

SUPPORTED LIBRARIES

155       By  default, libmongoc will attempt to find a supported TLS library and
156       enable TLS support. This is controlled by the  cmake  flag  ENABLE_SSL,
157       which is set to AUTO by default. Valid values are:
158
159AUTO  the  default behavior. Link to the system's native TLS library,
160         or attempt to find OpenSSL.
161
162DARWIN link to Secure Transport, the native TLS library on macOS.
163
164WINDOWS link to Secure Channel, the native TLS library on Windows.
165
166OPENSSL link to OpenSSL (libssl). An optional  install  path  may  be
167         specified with OPENSSL_ROOT.
168
169LIBRESSL link to LibreSSL's libtls. (LibreSSL's compatible libssl may
170         be linked to by setting OPENSSL).
171
172OFF disable TLS support.
173
174   OpenSSL
175       The MongoDB C Driver uses OpenSSL, if  available,  on  Linux  and  Unix
176       platforms (besides macOS). Industry best practices and some regulations
177       require the use of TLS 1.1 or newer, which requires  at  least  OpenSSL
178       1.0.1. Check your OpenSSL version like so:
179
180          $ openssl version
181
182       Ensure  your  system's OpenSSL is a recent version (at least 1.0.1), or
183       install a recent version in a non-system  path  and  build  against  it
184       with:
185
186          cmake -DOPENSSL_ROOT_DIR=/absolute/path/to/openssl
187
188       When compiled against OpenSSL, the driver will attempt to load the sys‐
189       tem default certificate store, as configured by the distribution.  That
190       can  be  overridden  by  setting  the  tlsCAFile URI option or with the
191       fields ca_file and ca_dir in the mongoc_ssl_opt_t.
192
193       The Online Certificate Status Protocol (OCSP) (see RFC 6960)  is  fully
194       supported when using OpenSSL 1.0.1+ with the following notes:
195
196       • When  a  crl_file  is set with mongoc_ssl_opt_t, and the crl_file re‐
197         vokes the server's certificate, the certificate is considered revoked
198         (even if the certificate has a valid stapled OCSP response)
199
200   LibreSSL / libtls
201       The  MongoDB C Driver supports LibreSSL through the use of OpenSSL com‐
202       patibility checks when configured to compile against openssl.  It  also
203       supports  the  new  libtls library when configured to build against li‐
204       bressl.
205
206       When compiled against the Windows native libraries, the crl_file option
207       of  a  mongoc_ssl_opt_t  is  not  supported, and will issue an error if
208       used.
209
210       Setting  tlsDisableOCSPEndpointCheck  and  tlsDisableCertificateRevoca‐
211       tionCheck has no effect.
212
213       The  Online  Certificate  Status Protocol (OCSP) (see RFC 6960) is par‐
214       tially supported with the following notes:
215
216       • The Must-Staple extension (see RFC 7633) is ignored.  Connection  may
217         continue  if  a  Must-Staple certificate is presented with no stapled
218         response (unless the client receives a revoked response from an  OCSP
219         responder).
220
221       • Connection  will  continue  if a Must-Staple certificate is presented
222         without a stapled response and the OCSP responder is down.
223
224   Native TLS Support on Windows (Secure Channel)
225       The MongoDB C Driver supports the Windows native  TLS  library  (Secure
226       Channel, or SChannel), and its native crypto library (Cryptography API:
227       Next Generation, or CNG).
228
229       When compiled against the Windows native libraries, the  ca_dir  option
230       of  a  mongoc_ssl_opt_t  is  not  supported, and will issue an error if
231       used.
232
233       Encrypted PEM files (e.g., setting tlsCertificateKeyPassword) are  also
234       not supported, and will result in error when attempting to load them.
235
236       When  tlsCAFile  is set, the driver will only allow server certificates
237       issued by the authority (or authorities) provided. When no tlsCAFile is
238       set, the driver will look up the Certificate Authority using the System
239       Local Machine Root certificate store to confirm the  provided  certifi‐
240       cate.
241
242       When  crl_file is set with mongoc_ssl_opt_t, the driver will import the
243       revocation list to the System Local Machine Root certificate store.
244
245       Setting tlsDisableOCSPEndpointCheck has no effect.
246
247       The Online Certificate Status Protocol (OCSP) (see RFC  6960)  is  par‐
248       tially supported with the following notes:
249
250       • The  Must-Staple  extension (see RFC 7633) is ignored. Connection may
251         continue if a Must-Staple certificate is presented  with  no  stapled
252         response  (unless the client receives a revoked response from an OCSP
253         responder).
254
255       • When a crl_file is set with mongoc_ssl_opt_t, and  the  crl_file  re‐
256         vokes  the  server's certificate, the OCSP response takes precedence.
257         E.g. if the server presents a certificate with a valid  stapled  OCSP
258         response,  the  certificate  is considered valid even if the crl_file
259         marks it as revoked.
260
261       • Connection will continue if a Must-Staple  certificate  is  presented
262         without a stapled response and the OCSP responder is down.
263
264   Native TLS Support on macOS / Darwin (Secure Transport)
265       The  MongoDB  C Driver supports the Darwin (OS X, macOS, iOS, etc.) na‐
266       tive TLS library (Secure Transport),  and  its  native  crypto  library
267       (Common Crypto, or CC).
268
269       When compiled against Secure Transport, the ca_dir and crl_file options
270       of a mongoc_ssl_opt_t are not supported. An error is issued  if  either
271       are used.
272
273       When  tlsCAFile  is set, the driver will only allow server certificates
274       issued by the authority (or authorities) provided. When no tlsCAFile is
275       set,  the  driver will use the Certificate Authorities in the currently
276       unlocked keychains.
277
278       Setting  tlsDisableOCSPEndpointCheck  and  tlsDisableCertificateRevoca‐
279       tionCheck has no effect.
280
281       The  Online  Certificate  Status Protocol (OCSP) (see RFC 6960) is par‐
282       tially supported with the following notes.
283
284       • The Must-Staple extension (see RFC 7633) is ignored.  Connection  may
285         continue  if  a  Must-Staple certificate is presented with no stapled
286         response (unless the client receives a revoked response from an  OCSP
287         responder).
288
289       • Connection  will  continue  if a Must-Staple certificate is presented
290         without a stapled response and the OCSP responder is down.
291

AUTHOR

293       MongoDB, Inc
294
296       2017-present, MongoDB, Inc
297
298
299
300
3011.24.3                           Aug 17, 2023        MONGOC_CONFIGURING_TLS(3)
Impressum