NAME

       mongoc_ssl_opt_t - mongoc_ssl_opt_t

SYNOPSIS

          typedef struct {
             const char *pem_file;
             const char *pem_pwd;
             const char *ca_file;
             const char *ca_dir;
             const char *crl_file;
             bool weak_cert_validation;
             bool allow_invalid_hostname;
             void *padding[7];
          } mongoc_ssl_opt_t;

DESCRIPTION

       This   structure   is   used   to   set   the   SSL   options  for  a  mongoc_client_t  or
       mongoc_client_pool_t.

       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.

       As of 1.4.0, the mongoc_client_pool_set_ssl_opts and mongoc_client_set_ssl_opts  will  not
       only  shallow  copy  the  struct,  but  will also copy the const char*. It is therefore no
       longer needed to make sure the values remain valid after setting them.

CONFIGURATION THROUGH URI OPTIONS

       Most of the configurable options can be using the Connection URI.

                       ┌───────────────────────┬─────────────────────────────────┐
                       │mongoc_ssl_opt_t key   │ URI key                         │
                       ├───────────────────────┼─────────────────────────────────┤
                       │pem_file               │ sslClientCertificateKeyFile     │
                       ├───────────────────────┼─────────────────────────────────┤
                       │pem_pwd                │ sslClientCertificateKeyPassword │
                       ├───────────────────────┼─────────────────────────────────┤
                       │ca_file                │ sslCertificateAuthorityFile     │
                       ├───────────────────────┼─────────────────────────────────┤
                       │weak_cert_validation   │ sslAllowInvalidCertificates     │
                       ├───────────────────────┼─────────────────────────────────┤
                       │allow_invalid_hostname │ sslAllowInvalidHostnames        │
                       └───────────────────────┴─────────────────────────────────┘

CLIENT AUTHENTICATION

       When MongoDB is started with SSL enabled, it will by default require the client to provide
       a  client  certificate  issued  by a certificate authority specified by --sslCAFile, or an
       authority trusted by the native certificate store in use on the server.

       To provide the client certificate, the user must configure the pem_file to point at a  PEM
       armored certificate.

          mongoc_ssl_opt_t ssl_opts = {0};

          ssl_opts.pem_file = "/path/to/client-certificate.pem"

          /* Then set the client ssl_opts, when using a single client mongoc_client_t */
          mongoc_client_pool_set_ssl_opts (pool, &ssl_opts);

          /* or, set the pool ssl_opts, when using a the thread safe mongoc_client_pool_t */
          mongoc_client_set_ssl_opts (client, &ssl_opts);

SERVER CERTIFICATE VERIFICATION

       The  MongoDB  C  Driver  will automatically verify the validity of the server certificate,
       such as issued by configured Certificate Authority, hostname validation, and expiration.

       To overwrite this behaviour, it is possible to disable hostname validation,  and/or  allow
       otherwise    invalid    certificates.    This    behaviour   is   controlled   using   the
       allow_invalid_hostname and weak_cert_validation fields. By default, both are set to false.
       It  is  not  recommended  to  change these defaults as it exposes the client to Man In The
       Middle attacks (when allow_invalid_hostname is set)  and  otherwise  invalid  certificates
       when weak_cert_validation is set to true.

NATIVE TLS SUPPORT ON LINUX (OPENSSL)

       The  MongoDB  C  Driver supports the dominating TLS library (OpenSSL) and crypto libraries
       (OpenSSL's libcrypto) on Linux and Unix platforms.

       Support for OpenSSL 1.1 and later was added in 1.4.0.

       When compiled against OpenSSL,  the  driver  will  attempt  to  load  the  system  default
       certificate  store,  as  configured by the distribution, if the ca_file and ca_dir are not
       set.

LIBRESSL / LIBTLS

       The MongoDB C Driver supports LibreSSL through the use  of  OpenSSL  compatibility  checks
       when  configured  to compile against openssl. It also supports the new libtls library when
       configured to build against libressl.

NATIVE TLS SUPPORT ON WINDOWS (SECURE CHANNEL)

       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).

       When  compiled  against  the Windows native libraries, the ca_dir option is not supported,
       and will issue an error if used.

       Encrypted PEM files (e.g., requiring pem_pwd) are also not supported, and will  result  in
       error when attempting to load them.

       When  ca_file  is  provided,  the driver will only allow server certificates issued by the
       authority (or authorities) provided. When no ca_file is provided, the driver will look  up
       the Certificate Authority using the System Local Machine Root certificate store to confirm
       the provided certificate.

       When crl_file is provided, the driver will import the revocation list to the System  Local
       Machine Root certificate store.

NATIVE TLS SUPPORT ON MAC OS X / DARWIN (SECURE TRANSPORT)

       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).

       When compiled against Secure Transport, the ca_dir option is not supported, and will issue
       an error if used.

       When  ca_file  is  provided,  the driver will only allow server certificates issued by the
       authority (or authorities) provided. When no ca_file is provided, the driver will use  the
       Certificate Authorities in the currently unlocked keychains.

SEE ALSO

       • mongoc_client_set_ssl_opts

       • mongoc_client_pool_set_ssl_opts

AUTHOR

       MongoDB, Inc

COPYRIGHT

       2018, MongoDB, Inc