.\" Man page generated from reStructuredText.
.
.TH "MONGOC_CONFIGURING_TLS" "3" "Jun 04, 2021" "1.17.6" "libmongoc"
.SH NAME
mongoc_configuring_tls \- Configuring TLS
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH CONFIGURATION WITH URI OPTIONS
.sp
Enable TLS by including \fBtls=true\fP the URI.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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);
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The following URI options may be used to further configure TLS:
.TS
center;
|l|l|l|.
_
T{
Constant
T}	T{
Key
T}	T{
Description
T}
_
T{
MONGOC_URI_TLS
T}	T{
tls
T}	T{
{true|false}, indicating if TLS must be used.
T}
_
T{
MONGOC_URI_TLSCERTIFICATEKEYFILE
T}	T{
tlscertificatekeyfile
T}	T{
Path to PEM formatted Private Key, with its Public Certificate concatenated at the end.
T}
_
T{
MONGOC_URI_TLSCERTIFICATEKEYPASSWORD
T}	T{
tlscertificatekeypassword
T}	T{
The password, if any, to use to unlock encrypted Private Key.
T}
_
T{
MONGOC_URI_TLSCAFILE
T}	T{
tlscafile
T}	T{
One, or a bundle of, Certificate Authorities whom should be considered to be trusted.
T}
_
T{
MONGOC_URI_TLSALLOWINVALIDCERTIFICATES
T}	T{
tlsallowinvalidcertificates
T}	T{
Accept and ignore certificate verification errors (e.g. untrusted issuer, expired, etc.)
T}
_
T{
MONGOC_URI_TLSALLOWINVALIDHOSTNAMES
T}	T{
tlsallowinvalidhostnames
T}	T{
Ignore hostname verification of the certificate (e.g. Man In The Middle, using valid certificate, but issued for another hostname)
T}
_
T{
MONGOC_URI_TLSINSECURE
T}	T{
tlsinsecure
T}	T{
{true|false}, indicating if insecure TLS options should be used. Currently this implies MONGOC_URI_TLSALLOWINVALIDCERTIFICATES and MONGOC_URI_TLSALLOWINVALIDHOSTNAMES.
T}
_
T{
MONGOC_URI_TLSDISABLECERTIFICATEREVOCATIONCHECK
T}	T{
tlsdisablecertificaterevocationcheck
T}	T{
{true|false}, indicates if revocation checking (CRL / OCSP) should be disabled.
T}
_
T{
MONGOC_URI_TLSDISABLEOCSPENDPOINTCHECK
T}	T{
tlsdisableocspendpointcheck
T}	T{
{true|false}, indicates if OCSP responder endpoints should not be requested when an OCSP response is not stapled.
T}
_
.TE
.SH CONFIGURATION WITH MONGOC_SSL_OPT_T
.sp
Alternatively, the \fBmongoc_ssl_opt_t\fP struct may be used to configure TLS with \fBmongoc_client_set_ssl_opts()\fP or \fBmongoc_client_pool_set_ssl_opts()\fP\&. Most of the configurable options can be set using the \fI\%Connection String URI\fP\&.
.TS
center;
|l|l|.
_
T{
\fBmongoc_ssl_opt_t key\fP
T}	T{
\fBURI key\fP
T}
_
T{
pem_file
T}	T{
tlsClientCertificateKeyFile
T}
_
T{
pem_pwd
T}	T{
tlsClientCertificateKeyPassword
T}
_
T{
ca_file
T}	T{
tlsCAFile
T}
_
T{
weak_cert_validation
T}	T{
tlsAllowInvalidCertificates
T}
_
T{
allow_invalid_hostname
T}	T{
tlsAllowInvalidHostnames
T}
_
.TE
.sp
The only exclusions are \fBcrl_file\fP and \fBca_dir\fP\&. Those may only be set with \fBmongoc_ssl_opt_t\fP\&.
.SH CLIENT AUTHENTICATION
.sp
When MongoDB is started with TLS enabled, it will by default require the client to provide a client certificate issued by a certificate authority specified by \fB\-\-tlsCAFile\fP, or an authority trusted by the native certificate store in use on the server.
.sp
To provide the client certificate, set the \fBtlsCertificateKeyFile\fP in the URI to a PEM armored certificate file.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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);
.ft P
.fi
.UNINDENT
.UNINDENT
.SH SERVER CERTIFICATE VERIFICATION
.sp
The MongoDB C Driver will automatically verify the validity of the server certificate, such as issued by configured Certificate Authority, hostname validation, and expiration.
.sp
To overwrite this behavior, it is possible to disable hostname validation, OCSP endpoint revocation checking, revocation checking entirely, and allow invalid certificates.
.sp
This behavior is controlled using the \fBtlsAllowInvalidHostnames\fP, \fBtlsDisableOCSPEndpointCheck\fP, \fBtlsDisableCertificateRevocationCheck\fP, and \fBtlsAllowInvalidCertificates\fP options respectively. By default, all are set to \fBfalse\fP\&.
.sp
It is not recommended to change these defaults as it exposes the client to \fIMan In The Middle\fP attacks (when \fBtlsAllowInvalidHostnames\fP is set), invalid certificates (when \fBtlsAllowInvalidCertificates\fP is set), or potentially revoked certificates (when \fBtlsDisableOCSPEndpointCheck\fP or \fBtlsDisableCertificateRevocationCheck\fP are set).
.SH SUPPORTED LIBRARIES
.sp
By default, libmongoc will attempt to find a supported TLS library and enable TLS support. This is controlled by the cmake flag \fBENABLE_SSL\fP, which is set to \fBAUTO\fP by default. Valid values are:
.INDENT 0.0
.IP \(bu 2
\fBAUTO\fP the default behavior. Link to the system\(aqs native TLS library, or attempt to find OpenSSL.
.IP \(bu 2
\fBDARWIN\fP link to Secure Transport, the native TLS library on macOS.
.IP \(bu 2
\fBWINDOWS\fP link to Secure Channel, the native TLS library on Windows.
.IP \(bu 2
\fBOPENSSL\fP link to OpenSSL (libssl). An optional install path may be specified with \fBOPENSSL_ROOT\fP\&.
.IP \(bu 2
\fBLIBRESSL\fP link to LibreSSL\(aqs libtls. (LibreSSL\(aqs compatible libssl may be linked to by setting \fBOPENSSL\fP).
.IP \(bu 2
\fBOFF\fP disable TLS support.
.UNINDENT
.SS OpenSSL
.sp
The MongoDB C Driver uses OpenSSL, if available, 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. Check your OpenSSL version like so:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ openssl version
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Ensure your system\(aqs OpenSSL is a recent version (at least 1.0.1), or install a recent version in a non\-system path and build against it with:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
cmake \-DOPENSSL_ROOT_DIR=/absolute/path/to/openssl
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
When 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 \fBtlsCAFile\fP URI option or with the fields \fBca_file\fP and \fBca_dir\fP in the \fBmongoc_ssl_opt_t\fP\&.
.sp
The Online Certificate Status Protocol (OCSP) (see \fI\%RFC 6960\fP) is fully supported when using OpenSSL 1.0.1+ with the following notes:
.INDENT 0.0
.IP \(bu 2
When a \fBcrl_file\fP is set with \fBmongoc_ssl_opt_t\fP, and the \fBcrl_file\fP revokes the server\(aqs certificate, the certificate is considered revoked (even if the certificate has a valid stapled OCSP response)
.UNINDENT
.SS LibreSSL / libtls
.sp
The MongoDB C Driver supports LibreSSL through the use of OpenSSL compatibility checks when configured to compile against \fBopenssl\fP\&. It also supports the new \fBlibtls\fP library when configured to build against \fBlibressl\fP\&.
.sp
When compiled against the Windows native libraries, the \fBcrl_file\fP option of a \fBmongoc_ssl_opt_t\fP is not supported, and will issue an error if used.
.sp
Setting \fBtlsDisableOCSPEndpointCheck\fP and \fBtlsDisableCertificateRevocationCheck\fP has no effect.
.sp
The Online Certificate Status Protocol (OCSP) (see \fI\%RFC 6960\fP) is partially supported with the following notes:
.INDENT 0.0
.IP \(bu 2
The Must\-Staple extension (see \fI\%RFC 7633\fP) is ignored. Connection may continue if a Must\-Staple certificate is presented with no stapled response (unless the client receives a revoked response from an OCSP responder).
.IP \(bu 2
Connection will continue if a Must\-Staple certificate is presented without a stapled response and the OCSP responder is down.
.UNINDENT
.SS Native TLS Support on Windows (Secure Channel)
.sp
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).
.sp
When compiled against the Windows native libraries, the \fBca_dir\fP option of a \fBmongoc_ssl_opt_t\fP is not supported, and will issue an error if used.
.sp
Encrypted PEM files (e.g., setting \fBtlsCertificateKeyPassword\fP) are also not supported, and will result in error when attempting to load them.
.sp
When \fBtlsCAFile\fP is set, the driver will only allow server certificates issued by the authority (or authorities) provided. When no \fBtlsCAFile\fP is set, the driver will look up the Certificate Authority using the \fBSystem Local Machine Root\fP certificate store to confirm the provided certificate.
.sp
When \fBcrl_file\fP is set with \fBmongoc_ssl_opt_t\fP, the driver will import the revocation list to the \fBSystem Local Machine Root\fP certificate store.
.sp
Setting \fBtlsDisableOCSPEndpointCheck\fP has no effect.
.sp
The Online Certificate Status Protocol (OCSP) (see \fI\%RFC 6960\fP) is partially supported with the following notes:
.INDENT 0.0
.IP \(bu 2
The Must\-Staple extension (see \fI\%RFC 7633\fP) is ignored. Connection may continue if a Must\-Staple certificate is presented with no stapled response (unless the client receives a revoked response from an OCSP responder).
.IP \(bu 2
When a \fBcrl_file\fP is set with \fBmongoc_ssl_opt_t\fP, and the \fBcrl_file\fP revokes the server\(aqs certificate, the OCSP response takes precedence. E.g. if the server presents a certificate with a valid stapled OCSP response, the certificate is considered valid even if the \fBcrl_file\fP marks it as revoked.
.IP \(bu 2
Connection will continue if a Must\-Staple certificate is presented without a stapled response and the OCSP responder is down.
.UNINDENT
.SS Native TLS Support on macOS / Darwin (Secure Transport)
.sp
The MongoDB C Driver supports the Darwin (OS X, macOS, iOS, etc.) native TLS library (Secure Transport), and its native crypto library (Common Crypto, or CC).
.sp
When compiled against Secure Transport, the \fBca_dir\fP and \fBcrl_file\fP options of a \fBmongoc_ssl_opt_t\fP are not supported. An error is issued if either are used.
.sp
When \fBtlsCAFile\fP is set, the driver will only allow server certificates issued by the authority (or authorities) provided. When no \fBtlsCAFile\fP is set, the driver will use the Certificate Authorities in the currently unlocked keychains.
.sp
Setting \fBtlsDisableOCSPEndpointCheck\fP and \fBtlsDisableCertificateRevocationCheck\fP has no effect.
.sp
The Online Certificate Status Protocol (OCSP) (see \fI\%RFC 6960\fP) is partially supported with the following notes.
.INDENT 0.0
.IP \(bu 2
The Must\-Staple extension (see \fI\%RFC 7633\fP) is ignored. Connection may continue if a Must\-Staple certificate is presented with no stapled response (unless the client receives a revoked response from an OCSP responder).
.IP \(bu 2
Connection will continue if a Must\-Staple certificate is presented without a stapled response and the OCSP responder is down.
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.