1MONGOC_SSL_OPT_T(3) libmongoc MONGOC_SSL_OPT_T(3)
2
6 mongoc_ssl_opt_t - mongoc_ssl_opt_t
7
9 typedef struct {
10 const char *pem_file;
11 const char *pem_pwd;
12 const char *ca_file;
13 const char *ca_dir;
14 const char *crl_file;
15 bool weak_cert_validation;
16 bool allow_invalid_hostname;
17 void *padding[7];
18 } mongoc_ssl_opt_t;
19
21 This structure is used to set the SSL options for a mongoc_client_t or
22 mongoc_client_pool_t.
23 Beginning in version 1.2.0, once a pool or client has any SSL options
25 set, all connections use SSL, even if ssl=true is omitted from the Mon‐
26 goDB URI. Before, SSL options were ignored unless ssl=true was included
27 in the URI.
28 As of 1.4.0, the mongoc_client_pool_set_ssl_opts and mon‐
30 goc_client_set_ssl_opts will not only shallow copy the struct, but will
31 also copy the const char*. It is therefore no longer needed to make
32 sure the values remain valid after setting them.
33
35 Most of the configurable options can be using the Connection URI.
36 ┌───────────────────────┬──────────────────────────┐
38 │mongoc_ssl_opt_t key │ URI key │
39 ├───────────────────────┼──────────────────────────┤
40 │pem_file │ sslClientCertificateKey‐ │
41 │ │ File │
42 ├───────────────────────┼──────────────────────────┤
43 │pem_pwd │ sslClientCertificateKey‐ │
44 │ │ Password │
45 ├───────────────────────┼──────────────────────────┤
46 │ca_file │ sslCertificateAuthority‐ │
47 │ │ File │
48 ├───────────────────────┼──────────────────────────┤
49 │weak_cert_validation │ sslAllowInvalidCertifi‐ │
50 │ │ cates │
51 ├───────────────────────┼──────────────────────────┤
52 │allow_invalid_hostname │ sslAllowInvalidHostnames │
53 └───────────────────────┴──────────────────────────┘
54
56 When MongoDB is started with SSL enabled, it will by default require
57 the client to provide a client certificate issued by a certificate
58 authority specified by --sslCAFile, or an authority trusted by the
59 native certificate store in use on the server.
60 To provide the client certificate, the user must configure the pem_file
62 to point at a PEM armored certificate.
63 mongoc_ssl_opt_t ssl_opts = {0};
65 ssl_opts.pem_file = "/path/to/client-certificate.pem"
67 /* Then set the client ssl_opts, when using a single client mongoc_client_t */
69 mongoc_client_set_ssl_opts (client, &ssl_opts);
70 /* or, set the pool ssl_opts, when using a the thread safe mongoc_client_pool_t */
72 mongoc_client_pool_set_ssl_opts (pool, &ssl_opts);
73
75 The MongoDB C Driver will automatically verify the validity of the
76 server certificate, such as issued by configured Certificate Authority,
77 hostname validation, and expiration.
78 To overwrite this behaviour, it is possible to disable hostname valida‐
80 tion, and/or allow otherwise invalid certificates. This behaviour is
81 controlled using the allow_invalid_hostname and weak_cert_validation
82 fields. By default, both are set to false. It is not recommended to
83 change these defaults as it exposes the client to Man In The Middle
84 attacks (when allow_invalid_hostname is set) and otherwise invalid cer‐
85 tificates when weak_cert_validation is set to true.
86
88 The MongoDB C Driver uses OpenSSL, if available, on Linux and Unix
89 platforms (besides macOS). Industry best practices and some regulations
90 require the use of TLS 1.1 or newer, which requires at least OpenSSL
91 1.0.1. Check your OpenSSL version like so:
92 $ openssl version
94 Ensure your system's OpenSSL is a recent version (at least 1.0.1), or
96 install a recent version in a non-system path and build against it
97 with:
98 cmake -DOPENSSL_ROOT_DIR=/absolute/path/to/openssl
100 When compiled against OpenSSL, the driver will attempt to load the sys‐
102 tem default certificate store, as configured by the distribution, if
103 the ca_file and ca_dir are not set.
104
106 The MongoDB C Driver supports LibreSSL through the use of OpenSSL com‐
107 patibility checks when configured to compile against openssl. It also
108 supports the new libtls library when configured to build against
109 libressl.
110
112 The MongoDB C Driver supports the Windows native TLS library (Secure
113 Channel, or SChannel), and its native crypto library (Cryptography API:
114 Next Generation, or CNG).
115 When compiled against the Windows native libraries, the ca_dir option
117 is not supported, and will issue an error if used.
118 Encrypted PEM files (e.g., requiring pem_pwd) are also not supported,
120 and will result in error when attempting to load them.
121 When ca_file is provided, the driver will only allow server certifi‐
123 cates issued by the authority (or authorities) provided. When no
124 ca_file is provided, the driver will look up the Certificate Authority
125 using the System Local Machine Root certificate store to confirm the
126 provided certificate.
127 When crl_file is provided, the driver will import the revocation list
129 to the System Local Machine Root certificate store.
130
132 The MongoDB C Driver supports the Darwin (OS X, macOS, iOS, etc.)
133 native TLS library (Secure Transport), and its native crypto library
134 (Common Crypto, or CC).
135 When compiled against Secure Transport, the ca_dir option is not sup‐
137 ported, and will issue an error if used.
138 When ca_file is provided, the driver will only allow server certifi‐
140 cates issued by the authority (or authorities) provided. When no
141 ca_file is provided, the driver will use the Certificate Authorities in
142 the currently unlocked keychains.
143
145 · mongoc_client_set_ssl_opts
146 · mongoc_client_pool_set_ssl_opts
148
150 MongoDB, Inc
151
153 2017-present, MongoDB, Inc
1541.16.2 Feb 25, 2020 MONGOC_SSL_OPT_T(3)