|
20 | 20 | const char *ca_dir; |
21 | 21 | const char *crl_file; |
22 | 22 | bool weak_cert_validation; |
23 | | - void *padding [8]; |
| 23 | + bool allow_invalid_hostname; |
| 24 | + void *padding [7]; |
24 | 25 | } mongoc_ssl_opt_t; |
25 | 26 | ]]></code> |
26 | 27 | </section> |
27 | 28 |
|
28 | 29 | <section id="desc"> |
29 | 30 | <title>Description</title> |
30 | 31 | <p>This structure is used to set the SSL options for a <code xref="mongoc_client_t">mongoc_client_t</code> or <code xref="mongoc_client_pool_t">mongoc_client_pool_t</code>.</p> |
31 | | - <p>Beginning in version 1.2.0, once a pool or client has any SSL options set, all connections use SSL, even if "ssl=true" is omitted from the MongoDB URI. Before, SSL options were ignored unless "ssl=true" was included in the URI.</p> |
| 32 | + <p>Beginning in version 1.2.0, once a pool or client has any SSL options set, all connections use SSL, even if <code>ssl=true</code> is omitted from the MongoDB URI. Before, SSL options were ignored unless <code>ssl=true</code> was included in the URI.</p> |
| 33 | + <p>As of 1.4.0, the <code xref="mongoc_client_pool_set_ssl_opts">mongoc_client_pool_set_ssl_opts</code> and <code xref="mongoc_client_set_ssl_opts">mongoc_client_set_ssl_opts</code> will not only shallow copy the struct, but will also copy the <code>const char*</code>. It is therefore no longer needed to make sure the values remain valid after setting them.</p>. |
| 34 | + </section> |
| 35 | + |
| 36 | + <section id="client-authentication"> |
| 37 | + <title>Client Authentication</title> |
| 38 | + <p>When MongoDB is started with SSL enabled, it will by default require the client o provide a client certificate issued by a certificate authority specified by <code>--sslCAFile</code>, or an authority trusted by the native certificate store in use on the server.</p> |
| 39 | + <p>To provide the client certificate, the user must configure the <code>pem_file</code> to point at a PEM armored certificate.</p> |
| 40 | + <screen><code mime="text/x-csrc"><![CDATA[mongoc_ssl_opts_t ssl_opts = { 0 }; |
| 41 | +
|
| 42 | +ssl_opts.pem_file = "/path/to/client-certificate.pem" |
| 43 | +
|
| 44 | +/* Then set the client ssl_opts, when using a single client mongoc_client_t */ |
| 45 | +mongoc_client_pool_set_ssl_opts (pool, &ssl_opts); |
| 46 | +/* or, set the pool ssl_opts, when using a the thread safe mongoc_client_pool_t */ |
| 47 | +mongoc_client_set_ssl_opts (client, &ssl_opts);]]></code></screen> |
| 48 | + </section> |
| 49 | + |
| 50 | + <section id="certificate-verification"> |
| 51 | + <title>Server Certificate Verification</title> |
| 52 | + <p>The MongoDB C Driver will automatically verify the validity of the server certificate, such as issued by configured Certificate Authority, hostname validation, and expiration.</p> |
| 53 | + <p>To overwrite this behaviour, it is possible to disable hostname validation, and/or allow otherwise invalid certificates. This behaviour is controlled using the <code>allow_invalid_hostname</code> and <code>weak_cert_validation</code> fields. By default, both are set to <code>false</code>. It is not recommended to change these defaults as it exposes the client to <em>Man In The Middle</em> attacks (when <code>allow_invalid_hostname</code> is set) and otherwise invalid certificates when <code>weak_cert_validation</code> is set to <code>true</code>.</p> |
| 54 | + </section> |
| 55 | + |
| 56 | + <section id="nativetls-linux"> |
| 57 | + <title>Native TLS Support on Linux (OpenSSL)</title> |
| 58 | + <p>The MongoDB C Driver supports the dominating TLS library (OpenSSL) and crypto libraries (OpenSSL's libcrypto) on Linux and Unix platforms.</p> |
| 59 | + <p>Support for OpenSSL 1.1 and later was added in 1.4.0.</p> |
| 60 | + <p>When compiled against OpenSSL, the driver will attempt to load the system default certificate store, as configured by the distribution, if the <code>ca_file</code> and <code>ca_dir</code> are not set.</p> |
| 61 | + </section> |
| 62 | + |
| 63 | + <section id="nativetls-windows"> |
| 64 | + <title>Native TLS Support on Windows (Secure Channel)</title> |
| 65 | + <p>The MongoDB C Driver supports the Windows native TLS library (Secure |
| 66 | + Channel, or SChannel), and its native crypto library (Cryptography API: |
| 67 | + Next Generation, or CNG).</p> |
| 68 | + <p>When compiled against the Windows native libraries, the <code>ca_dir</code> |
| 69 | + option is not supported, and will issue an error if used.</p> |
| 70 | + <p>Encrypted PEM files (e.g., requiring <code>pem_pwd</code>) are also not |
| 71 | + supported, and will result in error when attempting to load them.</p> |
| 72 | + <p>When <code>ca_file</code> is provided, the driver will only allow server |
| 73 | + certificates issued by the authority (or authorities) provided. When no |
| 74 | + <code>ca_file</code> is provided, the driver will look up the Certificate |
| 75 | + Authority using the <sys>System Local Machine Root</sys> certificate |
| 76 | + store to confirm the provided certificate.</p> |
| 77 | + <p>When <code>crl_file</code> is provided, the driver will import the |
| 78 | + revocation list to the <sys>System Local Machine Root</sys> certificate |
| 79 | + store.</p> |
| 80 | + </section> |
| 81 | + |
| 82 | + <section id="nativetls-darwin"> |
| 83 | + <title>Native TLS Support on Mac OS X / Darwin (Secure Transport)</title> |
| 84 | + <p>The MongoDB C Driver supports the Darwin (OS X, macOS, iOS, etc.) native |
| 85 | + TLS library (Secure Transport), and its native crypto library (Common |
| 86 | + Crypto, or CC).</p> |
| 87 | + <p>When compiled against Secure Transport, the <code>ca_dir</code> |
| 88 | + option is not supported, and will issue an error if used.</p> |
| 89 | + <p>When <code>ca_file</code> is provided, the driver will only allow server |
| 90 | + certificates issued by the authority (or authorities) provided. When no |
| 91 | + <code>ca_file</code> is provided, the driver will use the Certificate |
| 92 | + Authorities in the currently unlocked keychains.</p> |
32 | 93 | </section> |
33 | 94 |
|
34 | 95 | <links type="topic" groups="function" style="2column"> |
|
0 commit comments