From 1d83ddd49131a3f372c1c2c56223150df165ba12 Mon Sep 17 00:00:00 2001 From: skerschb Date: Mon, 25 Jun 2018 19:43:45 -0400 Subject: [PATCH] DOCS-11426: Windows and Mac secure store --- .../option-ssl-certificateSelector.rst | 22 +++++++++++++ source/includes/options-mongo.yaml | 7 ++++ source/includes/options-mongod.yaml | 19 +++++++++++ source/includes/options-mongos.yaml | 7 ++++ source/includes/ssl-trusted-store.rst | 18 +++++++++++ source/reference/configuration-options.txt | 1 + source/reference/parameters.txt | 16 ++++++++++ source/reference/program/mongo.txt | 2 ++ source/reference/program/mongod.txt | 2 ++ source/reference/program/mongos.txt | 2 ++ source/release-notes/4.0.txt | 10 ++++++ source/tutorial/configure-ssl-clients.txt | 27 ++++++++++++++++ source/tutorial/configure-ssl.txt | 32 +++++++++++++++++-- source/tutorial/upgrade-cluster-to-ssl.txt | 7 ++++ 14 files changed, 170 insertions(+), 2 deletions(-) create mode 100644 source/includes/option-ssl-certificateSelector.rst create mode 100644 source/includes/ssl-trusted-store.rst diff --git a/source/includes/option-ssl-certificateSelector.rst b/source/includes/option-ssl-certificateSelector.rst new file mode 100644 index 00000000000..e6c49056135 --- /dev/null +++ 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. \ No newline at end of file diff --git a/source/includes/options-mongo.yaml b/source/includes/options-mongo.yaml index 316f0c9ddb9..215e801ff03 100644 --- 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: directive: option diff --git a/source/includes/options-mongod.yaml b/source/includes/options-mongod.yaml index 1cc354448bc..c44ad4838c8 100644 --- a/source/includes/options-mongod.yaml +++ b/source/includes/options-mongod.yaml @@ -1205,6 +1205,25 @@ description: | optional: false --- program: mongod +name: sslCertificateSelector +args: = +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 + =. 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 index cb604d8a2b7..65be2a55e96 100644 --- 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 new file mode 100644 index 00000000000..c6a126e13dd --- /dev/null +++ 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 +` 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 = 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 index 3ba7dc97303..a434b79ab5b 100644 --- a/source/reference/configuration-options.txt +++ b/source/reference/configuration-options.txt @@ -264,6 +264,7 @@ Core Options filePermissions: ssl: sslOnNormalPorts: # deprecated since 2.6 + certificateSelector: mode: PEMKeyFile: PEMKeyPassword: diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt index b63021ed2e7..292abbaaa5b 100644 --- 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 =. + + 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 index de589140d8f..eba63c664ab 100644 --- 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 index 39dd30b3d90..1bab28d3ba6 100644 --- 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 index bbb0c7a78c7..f9f008eb232 100644 --- 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 index f723d99eeaf..dc8ccdac99d 100644 --- 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 ` 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 index a5e9eeee93b..1b770fdc4f9 100644 --- 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 ` 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: = + Connect to MongoDB Instance Using Encryption ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/tutorial/configure-ssl.txt b/source/tutorial/configure-ssl.txt index 884c690f966..2c9a2acbc0c 100644 --- 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: = + + +.. tip:: + + If you are using :option:`--sslCertificateSelector ` or + :setting:`~net.ssl.certificateSelector`, the :option:`--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 index 051022e69c6..79704a27938 100644 --- a/source/tutorial/upgrade-cluster-to-ssl.txt +++ b/source/tutorial/upgrade-cluster-to-ssl.txt @@ -61,6 +61,13 @@ process: PEMKeyFile: CAFile: + .. note:: + + If you are using :option:`--sslCertificateSelector ` + or :setting:`~net.ssl.certificateSelector`, the :option:`--sslPEMKeyFile ` + option is invalid. See :doc:`instructions ` on how to configure + TLS/SSL with ``certificateSelector``. + #. Switch all clients to use TLS/SSL. See :ref:`ssl-clients`.