DOCS-11426: Windows and Mac secure store

skerschb · kay-kim · commit 6dd5d1066c6f · 2018-06-26T13:51:17.000-04:00
diff --git a/source/includes/option-ssl-certificateSelector.rst b/source/includes/option-ssl-certificateSelector.rst
@@ -0,0 +1,22 @@
+The following selectors are available.
+
+.. list-table::
+   :header-rows: 1
+   :widths: auto
+
+   * - property name
+     - value type
+     - value description
+     
+   * - subject
+     - ASCII string
+     - subject name or common name on certificate
+   * - thumbprint
+     - hex string
+     - certificate thumbprint
+     
+.. note::
+   
+   The term ``thumbprint`` refers to what is also frequently
+   referred to as a ``fingerprint``. It is a short sequence of bytes used
+   to identify a longer public key.
diff --git a/source/includes/options-mongo.yaml b/source/includes/options-mongo.yaml
@@ -241,6 +241,13 @@ description: |
 optional: true
 ---
 program: mongo
+name: sslCertificateSelector
+inherit:
+  name: sslCertificateSelector
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongo
 name: sslPEMKeyFile
 args: <filename>
 directive: option
diff --git a/source/includes/options-mongod.yaml b/source/includes/options-mongod.yaml
@@ -1205,6 +1205,25 @@ description: |
 optional: false
 ---
 program: mongod
+name: sslCertificateSelector
+args: <parameter>=<value>
+directive: option
+description: |
+
+  .. versionadded:: 4.0
+
+  Specifies the selector and value to search when using Windows or 
+  Mac system certificate store mechanisms.
+  
+  This option must be followed by a key value pair indicated by
+  <parameter>=<value>. In this case parameter is the name of the
+  selector.
+
+  .. include:: /includes/option-ssl-certificateSelector.rst
+  
+optional: true
+---
+program: mongod
 name: sslOnNormalPorts
 args: null
 directive: option
diff --git a/source/includes/options-mongos.yaml b/source/includes/options-mongos.yaml
@@ -259,6 +259,13 @@ inherit:
   file: options-shared.yaml
 ---
 program: mongos
+name: sslCertificateSelector
+inherit:
+  name: sslCertificateSelector
+  program: mongod
+  file: options-mongod.yaml
+---
+program: mongos
 name: sslMode
 inherit:
   name: sslMode
diff --git a/source/includes/ssl-trusted-store.rst b/source/includes/ssl-trusted-store.rst
@@ -0,0 +1,18 @@
+MacOS and Windows both offer system certificate stores that can be
+accessed across applications via OS specific APIs. Starting in MongoDB
+version 4.0, certificates can be retrieved from these stores by
+searching for them via certain well-defined selectors that are available
+in all certificates.
+
+On the command line you can pass the :option:`--sslCertificateSelector
+<mongod --sslCertificateSelector>` followed by the certificate selector
+you would like to use and the value of that selector.
+
+.. include:: /includes/option-ssl-certificateSelector.rst
+
+Use the selectors by passing <parameter>=<value> on the
+command line. For example, for a certificate with the common name or
+subject ``my.dev.server``, you would use:
+
+
+
diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt
@@ -264,6 +264,7 @@ Core Options
          filePermissions: <int>
       ssl:
          sslOnNormalPorts: <boolean>  # deprecated since 2.6
+         certificateSelector: <string>
          mode: <string>
          PEMKeyFile: <string>
          PEMKeyPassword: <string>
diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt
@@ -294,6 +294,22 @@ Authentication Parameters
       - :method:`db.createUser()`
       - :method:`db.updateUser()`
 
+.. parameter:: sslCertificateSelector
+
+  .. versionadded:: 4.0
+
+  Specifies the ``selector`` and value to search when using Windows or 
+  Mac Secure Transport mechanisms for certificate store.
+  
+  When passed as a parameter on the command line, this option must be
+  followed by a key value pair indicated by <parameter>=<value>.
+
+  In a config file use the :setting:`net.ssl.certificateSelector` followed
+  by the parameter/value pair.
+
+  .. include:: /includes/option-ssl-certificateSelector.rst
+
+
 .. parameter:: sslMode
 
    .. versionadded:: 2.6
diff --git a/source/reference/program/mongo.txt b/source/reference/program/mongo.txt
@@ -119,6 +119,8 @@ TLS/SSL Options
 
 .. include:: /includes/option/option-mongo-sslCAFile.rst
 
+.. include:: /includes/option/option-mongo-sslCertificateSelector.rst
+
 .. include:: /includes/option/option-mongo-sslCRLFile.rst
 
 .. include:: /includes/option/option-mongo-sslFIPSMode.rst
diff --git a/source/reference/program/mongod.txt b/source/reference/program/mongod.txt
@@ -261,6 +261,8 @@ TLS/SSL Options
 
 .. include:: /includes/option/option-mongod-sslClusterFile.rst
 
+.. include:: /includes/option/option-mongod-sslCertificateSelector.rst
+
 .. include:: /includes/option/option-mongod-sslClusterPassword.rst
 
 .. include:: /includes/option/option-mongod-sslCAFile.rst
diff --git a/source/reference/program/mongos.txt b/source/reference/program/mongos.txt
@@ -129,6 +129,8 @@ TLS/SSL Options
 
 .. include:: /includes/option/option-mongos-sslCAFile.rst
 
+.. include:: /includes/option/option-mongos-sslCertificateSelector.rst
+
 .. include:: /includes/option/option-mongos-sslCRLFile.rst
 
 .. include:: /includes/option/option-mongos-sslAllowConnectionsWithoutCertificates.rst
diff --git a/source/release-notes/4.0.txt b/source/release-notes/4.0.txt
@@ -433,6 +433,16 @@ CA, specify that CA using :setting:`net.ssl.CAFile`.
 
 .. _4.0-deprecate-mmapv1:
 
+Enable System Store for SSL on Windows and Mac
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :option:`--sslCertificateSelector <mongo --sslCertificateSelector>` option
+(:setting:`net.ssl.certificateSelector` setting) allows
+:binary:`~bin.mongod`, :binary:`~bin.mongo` shell and
+:binary:`~bin.mongos` to use system ssl certificate stores for Windows
+and Mac.
+
+
 Deprecate MMAPv1
 ----------------
 
diff --git a/source/tutorial/configure-ssl-clients.txt b/source/tutorial/configure-ssl-clients.txt
@@ -53,9 +53,36 @@ settings, including:
 
 .. include:: /includes/extracts/ssl-facts-mongo-ssl-options-configure.rst
 
+.. versionadded:: 4.0
+
+- :option:`--sslCertificateSelector <mongo --sslCertificateSelector>` option if you
+  wish to use the system store for clients running on Mac or Windows.
+
+.. include:: /includes/extracts/mongo-ssl-options-configure.rst
+
+.. include:: /includes/extracts/clients-warning-sslCAFile.rst
+
 For a complete list of the :binary:`~bin.mongo` shell's TLS/SSL settings, see
 :ref:`mongo-shell-ssl`.
 
+Using System Stores for Storing Keys and Certificates for Mac and Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/ssl-trusted-store.rst
+
+.. code-block:: sh
+
+   mongo --ssl --sslCertificateSelector subject=my.dev.server
+
+Alternatively, use the :setting:`~net.ssl.certificateSelector` to
+configure the certificate storage selector with a config file.
+
+.. code-block:: yaml
+   
+   net:
+      ssl:
+         certificateSelector: <parameter>=<value>
+
 Connect to MongoDB Instance Using Encryption
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/source/tutorial/configure-ssl.txt b/source/tutorial/configure-ssl.txt
@@ -106,15 +106,45 @@ in the following example:
    format, various conversion tools exist, such as ``openssl pkcs8``
    and others.
 
+
 Procedures
 ----------
 
+.. versionadded:: 4.0
+
+Using System Stores for Storing Keys and Certificates for Mac and Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/ssl-trusted-store.rst
+
+.. code-block:: sh
+
+   mongod --sslMode requireSSL --sslCertificateSelector subject=my.dev.server
+
+Alternatively, use the :setting:`~net.ssl.certificateSelector` to
+configure the certificate storage selector with a config file.
+
+.. code-block:: yaml
+   
+   net:
+      ssl:
+         certificateSelector: <parameter>=<value>
+
+
+.. tip::    
+
+   If you are using :option:`--sslCertificateSelector <mongod --sslCertificateSelector>` or
+   :setting:`~net.ssl.certificateSelector`, the :option:`--sslPEMKeyFile
+   <mongod --sslPEMKeyFile>` is invalid. OCSP (Online Certificate Status Protocol) is
+   used to validate the revocation status of certificates.
+
 .. note::
 
    .. include:: /includes/extracts/default-bind-ip-security.rst
 
 .. _ssl-mongod-ssl-cert-key:
 
+
 Set Up ``mongod`` and ``mongos`` with TLS/SSL Certificate and Key
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -244,12 +274,10 @@ See :ref:`ssl-clients` for more information on connecting to
 
 Block Revoked Certificates for Clients
 ``````````````````````````````````````
-
 To prevent clients with revoked certificates from connecting, include
 the :setting:`sslCRLFile` to specify a :file:`.pem` file that contains
 revoked certificates.
 
-
 For example, the following :binary:`~bin.mongod` with TLS/SSL configuration
 includes the :setting:`sslCRLFile` setting:
 
diff --git a/source/tutorial/upgrade-cluster-to-ssl.txt b/source/tutorial/upgrade-cluster-to-ssl.txt
@@ -61,6 +61,13 @@ process:
             PEMKeyFile: <path to TLS/SSL certificate and key PEM file>
             CAFile: <path to root CA PEM file>
 
+   .. note::
+
+      If you are using :option:`--sslCertificateSelector <mongod --sslCertificateSelector>`
+      or :setting:`~net.ssl.certificateSelector`, the :option:`--sslPEMKeyFile <mongod --sslPEMKeyFile>` 
+      option is invalid. See :doc:`instructions </tutorial/configure-ssl>` on how to configure
+      TLS/SSL with ``certificateSelector``.
+
 
 #. Switch all clients to use TLS/SSL. See :ref:`ssl-clients`.
 
