Merge pull request #99 from atsansone/DOCSP-15123

(DOCSP-15123) Add note to tlsCertificateSelector option

Author: atsansone

source/images/certificate-import-wizard.png

@@ -1,5 +1,4 @@
-.. admonition:: Beta
-   :class: note
+.. note:: Beta Release
 
    The |mdb-shell| (``mongosh``) is currently available as a **Beta**
    release. The product, its features, and the corresponding

source/includes/admonitions/fact-mdb-shell-beta.rst

@@ -23,8 +23,9 @@ General Options
 .. option:: --eval <javascript>
 
    Evaluates a JavaScript expression that is specified as an argument.
-   :program:`mongo` does not load its own environment when evaluating code.
-   As a result many options of the shell environment are not available.
+   :program:`mongo` does not load its own environment when evaluating
+   code. As a result many options of the shell environment are not
+   available.
 
 .. option:: --help, -h
 
@@ -38,7 +39,7 @@ General Options
 
    Prevents the shell from sourcing and evaluating ``~/.mongorc.js`` on
    startup.
-   
+
 .. option:: --version
 
    Returns the |mdb-shell| release number.
@@ -52,15 +53,15 @@ Connection Options
    :binary:`~bin.mongod` or :binary:`~bin.mongos` is running. If this is
    not specified, the |mdb-shell| attempts to connect to a MongoDB
    process running on the localhost.
-   
+
    To connect to a replica set,
       Specify the :setting:`replica set name <~replication.replSetName>`
       and a seed list of set members. Use the following form:
-   
+
       .. code-block:: none
-   
+
          <replSetName>/<hostname1><:port>,<hostname2><:port>,<...>
-   
+
    For TLS/SSL connections (:option:`--tls <--tls>`),
      The |mdb-shell| shell verifies that the hostname
      (specified in the :option:`--host <--host>` option or the
@@ -70,7 +71,7 @@ Connection Options
      present, the |mdb-shell| does not match against the ``CN``. If
      the hostname does not match the ``SAN`` (or ``CN``), the
      |mdb-shell| shell fails to connect.
-   
+
    For `DNS seedlist connections <https://docs.mongodb.com/manual/reference/connection-string/#dns-seedlist-connection-format/>`_, 
       Specify the connection protocol as ``mongodb+srv``, followed by
       the DNS SRV hostname record and any options. The ``authSource``
@@ -82,9 +83,9 @@ Connection Options
       setting ``tls=false`` in the query string.
 
       .. example::
-   
+
          .. code-block:: none
-      
+   
             mongodb+srv://server.example.com/?connectionTimeout=3000ms
 
 .. option:: --port <port>
@@ -98,18 +99,18 @@ TLS Options
 ~~~~~~~~~~~
 
 .. option:: --tls
-   
+
    Enables connection to a :binary:`~bin.mongod` or
    :binary:`~bin.mongos` that has |tls-ssl| support enabled.
-   
+
    .. include:: /includes/fact-ssl-see-more.rst
 
 .. option:: --tlsCertificateKeyFile <filename>
-   
+
    Specifies the :file:`.pem` file that contains both the |tls-ssl|
    certificate and key for the :binary:`~bin.mongo` shell. Specify the
    file name of the :file:`.pem` file using relative or absolute paths.
-   
+
    This option is required when using the :option:`--tls <--tls>` option to connect to
    a :binary:`~bin.mongod` or :binary:`~bin.mongos` instance that
    requires :ref:`client certificates
@@ -119,76 +120,76 @@ TLS Options
    .. note::
 
       .. include:: /includes/fact-certificate-expiry-warning.rst
-   
+
    .. include:: /includes/fact-ssl-see-more.rst
 
 .. option:: --tlsCertificateKeyFilePassword <value>
-   
+
    Specifies the password to de-crypt the certificate-key file (i.e.
    :option:`--tlsCertificateKeyFile <--tlsCertificateKeyFile>`).
-   
+
    Use the
    :option:`--tlsCertificateKeyFilePassword
    <--tlsCertificateKeyFilePassword>` option only if the
    certificate-key file is encrypted. In all cases, the |mdb-shell|
    redacts the password from all logging and reporting output.
-   
+
    If the private key in the PEM file is encrypted and you do not
    specify the
    :option:`--tlsCertificateKeyFilePassword
    <--tlsCertificateKeyFilePassword>` option; the |mdb-shell| prompts
    for a passphrase.
-   
+
    See :ref:`ssl-certificate-password`.
-   
+
    .. include:: /includes/extracts/ssl-facts-see-more.rst
 
 .. option:: --tlsCAFile <filename>
-     
+  
    Specifies the :file:`.pem` file that contains the root certificate
    chain from the Certificate Authority. This file is used to validate
    the certificate presented by the
    :binary:`~bin.mongod`/:binary:`~bin.mongos` instance.
-   
+
    Specify the file name of the :file:`.pem` file using relative or
    absolute paths.
-   
+
    .. include:: /includes/extracts/ssl-facts-see-more.rst
 
 .. option:: --tlsCRLFile <filename>
-   
+
    Specifies the :file:`.pem` file that contains the Certificate
    Revocation List. Specify the file name of the :file:`.pem` file
    using relative or absolute paths.
-   
+
    .. include:: /includes/extracts/ssl-facts-see-more.rst
 
 .. option:: --tlsAllowInvalidHostnames
-   
+
    Disables the validation of the hostnames in the certificate presented
    by the :binary:`~bin.mongod`/:binary:`~bin.mongos` instance. Allows
    the |mdb-shell| to connect to MongoDB instances even if the hostname
    in the server certificates do not match the server's host.
-   
+
    .. include:: /includes/extracts/ssl-facts-see-more.rst
 
 .. option:: --tlsAllowInvalidCertificates
 
    .. versionadded:: 4.2
-   
+
    Bypasses the validation checks for the certificates presented by the
    :binary:`~bin.mongod`/:binary:`~bin.mongos` instance and allows
    connections to servers that present invalid certificates.
-   
+
    .. note::
-      
+
       Starting in MongoDB 4.0, if you specify
       :option:`--tlsAllowInvalidCertificates
       <--tlsAllowInvalidCertificates>` when using x.509
       authentication, an invalid certificate is only sufficient to
       establish a |tls-ssl| connection but is *insufficient* for
       authentication.
-   
+
    .. warning::
 
       Although available, avoid using the
@@ -209,32 +210,41 @@ TLS Options
       or :binary:`~bin.mongos` instances. If you only need to disable
       the validation of the hostname in the |tls-ssl| certificates, see
       :option:`--tlsAllowInvalidHostnames <--tlsAllowInvalidHostnames>`.
-   
+
    .. include:: /includes/extracts/ssl-facts-see-more.rst
 
 .. option:: --tlsCertificateSelector <parameter>=<value>
-   
+
    Available on Windows and macOS as an alternative to
    :option:`--tlsCertificateKeyFile <--tlsCertificateKeyFile>`.
-   
+
+   .. important:: Windows and Importing Private Keys
+
+      When you import your private key, you must mark it as exportable.
+      The Windows **Certificate Import Wizard** doesn't check this
+      option by default.
+
+      .. figure:: /images/certificate-import-wizard.png
+         :alt: Microsoft Certificate Import Wizard where the key marked as exportable
+
    The :option:`--tlsCertificateKeyFile <--tlsCertificateKeyFile>` and
-   :option:`--tlsCertificateSelector <--tlsCertificateSelector>` options
-   are mutually exclusive. You can only specify one.
+   :option:`--tlsCertificateSelector <--tlsCertificateSelector>`
+   options are mutually exclusive. You can only specify one.
 
    Specifies a certificate property in order to select a matching
    certificate from the operating system's certificate store.
 
-   :option:`--tlsCertificateSelector <--tlsCertificateSelector>` accepts
-   an argument of the format ``<property>=<value>`` where the property
-   can be one of the following:
+   :option:`--tlsCertificateSelector <--tlsCertificateSelector>`
+   accepts an argument of the format ``<property>=<value>`` where the
+   property can be one of the following:
 
    .. list-table::
       :header-rows: 1
 
       * - Property
         - Value type
         - Description
-    
+
       * - ``subject``
         - ASCII string
         - Subject name or common name on certificate
@@ -257,25 +267,25 @@ TLS Options
       .. include:: /includes/fact-certificate-expiry-warning.rst
 
 .. option:: --tlsDisabledProtocols <string>
-   
+
    Disables the specified TLS protocols. The option recognizes the
    following protocols:
-   
+
    - ``TLS1_0``
    - ``TLS1_1``
    - ``TLS1_2``
    - *(Starting in version 4.0.4, 3.6.9, 3.4.24)* ``TLS1_3``
-   
+
    - On macOS, you cannot disable ``TLS1_1`` and leave both ``TLS1_0``
      and ``TLS1_2`` enabled. You must also disable at least one of the
      other two; for example, ``TLS1_0,TLS1_1``.
-   
+
    - To list multiple protocols, specify as a comma separated list of
      protocols. For example ``TLS1_0,TLS1_1``.
-   
+
    - The specified disabled protocols overrides any default disabled
      protocols.
-   
+
    Starting in version 4.0, MongoDB disables the use of TLS 1.0 if TLS
    1.1+ is available on the system. To enable the
    disabled TLS 1.0, specify ``none`` to
@@ -285,11 +295,11 @@ Authentication Options
 ----------------------
 
 .. option:: --authenticationDatabase <dbname>
-   
+
    Specifies the authentication database where the specified
    :option:`--username <--username>` has been created. See
    :ref:`user-authentication-database`.
-   
+
 
    If you do not specify a value for
    :option:`--authenticationDatabase <--authenticationDatabase>`,
@@ -302,17 +312,17 @@ Authentication Options
 
    Specifies the authentication mechanism the |mdb-shell| uses to
    authenticate to the :binary:`~bin.mongod` or :binary:`~bin.mongos`.
-   
+
    .. note::
-   
+
       Starting in version 4.0:
-      
+   
       - MongoDB removes support for the deprecated MongoDB
         Challenge-Response (``MONGODB-CR``) authentication mechanism.
-   
+
       -  MongoDB adds support for SCRAM mechanism using the SHA-256 hash
          function (``SCRAM-SHA-256``).
-   
+
    .. list-table::
       :header-rows: 1
       :widths: 20 40
@@ -358,14 +368,14 @@ Authentication Options
    Specify the hostname of a service using
    :manual:`GSSAPI/Kerberos </core/kerberos>`. Only required if the
    hostname of a machine does not match the hostname resolved by DNS.
-   
+
    This option is available only in MongoDB Enterprise.
 
 .. option:: --gssapiServiceName
 
    Specify the name of the service using
    :manual:`GSSAPI/Kerberos </core/kerberos>`. Only required if the service does not use the default name of ``mongodb``.
-   
+
    This option is available only in MongoDB Enterprise.
 
 .. option:: --password <password>, -p <password>
@@ -391,10 +401,10 @@ Session Options
 ---------------
 
 .. option:: --retryWrites
-   
+
    Enables :manual:`retryable writes </core/retryable-writes/>` as the
    default for sessions in the |mdb-shell|.
-   
+
    For more information on sessions, see :ref:`sessions`.
 
 .. disableImplicitSessions