diff --git a/snooty.toml b/snooty.toml index 313d38d34..738f761bd 100644 --- a/snooty.toml +++ b/snooty.toml @@ -14,6 +14,7 @@ intersphinx = [ "https://www.mongodb.com/docs/atlas/objects.inv", toc_landing_pages = ["/quickstart", "/installation", + "/installation/verify", "reference/reference", "/connecting", "/topologies", @@ -53,4 +54,4 @@ targets = [ variant = "warning" value = """\ MongoDB ``mongosync`` binaries are not supported or tested for use with non-genuine MongoDB deployments. While the tools may work on these deployments, compatibility is not guaranteed. - """ \ No newline at end of file + """ diff --git a/source/includes/verification-gpg-results.rst b/source/includes/verification-gpg-results.rst new file mode 100644 index 000000000..7141eeba0 --- /dev/null +++ b/source/includes/verification-gpg-results.rst @@ -0,0 +1,17 @@ +If the key imports successfully, the command returns: + +.. code-block:: sh + :copyable: false + + gpg: key 3132835C1D925D5B: public key "MongoDB CLI Tools Release Signing Key " imported + gpg: Total number processed: 1 + gpg: imported: 1 + +If you have previously imported the key, the command returns: + +.. code-block:: sh + :copyable: false + + gpg: key 3132835C1D925D5B: "MongoDB CLI Tools Release Signing Key " not changed + gpg: Total number processed: 1 + gpg: unchanged: 1 diff --git a/source/includes/verify-signatures-before-you-begin.rst b/source/includes/verify-signatures-before-you-begin.rst new file mode 100644 index 000000000..f298de7f8 --- /dev/null +++ b/source/includes/verify-signatures-before-you-begin.rst @@ -0,0 +1,3 @@ +If you don't have ``mongosync`` installed, download the ``mongosync`` +package from the `Download Center +`__. diff --git a/source/includes/verify-signatures-intro.rst b/source/includes/verify-signatures-intro.rst new file mode 100644 index 000000000..05cffc2b1 --- /dev/null +++ b/source/includes/verify-signatures-intro.rst @@ -0,0 +1,4 @@ +The MongoDB release team digitally signs ``mongosync`` packages to +certify that the packages are a valid and unaltered MongoDB release. +Before you install ``mongosync``, you can use the digital signature to +validate the package. diff --git a/source/installation.txt b/source/installation.txt index bb1e3add2..ebc3fe069 100644 --- a/source/installation.txt +++ b/source/installation.txt @@ -24,3 +24,4 @@ These documents provide instructions to install {+c2c-full-product-name+}. Linux macOS + Verify Packages diff --git a/source/installation/verify.txt b/source/installation/verify.txt new file mode 100644 index 000000000..302416499 --- /dev/null +++ b/source/installation/verify.txt @@ -0,0 +1,33 @@ +.. _c2c-verify-signature: + +====================================== +Verify Integrity of mongosync Packages +====================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: tutorial + +.. include:: /includes/verify-signatures-intro.rst + +To learn how to verify ``mongosync`` packages, see the corresponding +page for your verification method: + +- :ref:`c2c-verify-signatures-macos` + +- :ref:`c2c-verify-signatures-gpg` + +- :ref:`c2c-verify-signatures-rpm` + +.. toctree:: + :titlesonly: + + macOS + Linux + RHEL diff --git a/source/installation/verify/gpg.txt b/source/installation/verify/gpg.txt new file mode 100644 index 000000000..eaab3d91d --- /dev/null +++ b/source/installation/verify/gpg.txt @@ -0,0 +1,89 @@ +.. _c2c-verify-signatures-gpg: + +================================ +Verify Packages with GPG (Linux) +================================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: tutorial + +.. include:: /includes/verify-signatures-intro.rst + +This page describes how to use GPG to verify Linux packages. + +Before you Begin +---------------- + +.. include:: /includes/verify-signatures-before-you-begin.rst + +Steps +----- + +.. procedure:: + :style: normal + + .. step:: Import the MongoDB Server Tools public key + + .. code-block:: sh + + curl https://pgp.mongodb.com/server-Tools.asc | gpg --import + + .. include:: /includes/verification-gpg-results.rst + + .. step:: Download the mongosync public signature + + To download the ``mongosync`` public signature, run the following + command, replacing the placeholder values with your platform, + architecture, and ``mongosync`` version: + + .. code-block:: sh + + curl -LO https://s3.amazonaws.com/downloads.mongodb.org/tools/mongosync/mongosync---.tgz.sig + + .. example:: + + The following URL contains the signature file for ``mongosync`` + on Amazon Linux 2, version {+latest-version+}: + + ``https://s3.amazonaws.com/downloads.mongodb.org/tools/mongosync/mongosync-amazon2-x86_64-{+latest-version+}.tgz.sig`` + + .. step:: Verify the package + + .. code-block:: sh + + gpg --verify + + If the package is signed by MongoDB, the command returns: + + .. code-block:: sh + :copyable: false + + gpg: Signature made Wed 19 Feb 2025 02:19:15 PM EST + gpg: using RSA key D4E45C292A5C94962F0D10E13132835C1D925D5B + gpg: Good signature from "MongoDB CLI Tools Release Signing Key " [unknown] + + If the package is signed but the signing key is not added to your + local ``trustdb``, the command returns: + + .. code-block:: sh + :copyable: false + + gpg: WARNING: This key is not certified with a trusted signature! + gpg: There is no indication that the signature belongs to the owner. + + If the package is not properly signed, the command returns an + error message: + + .. code-block:: sh + :copyable: false + + gpg: Signature made Wed 19 Feb 2025 02:19:15 PM EST + gpg: using RSA key D4E45C292A5C94962F0D10E13132835C1D925D5B + gpg: BAD signature from "MongoDB CLI Tools Release Signing Key " [unknown] diff --git a/source/installation/verify/macos.txt b/source/installation/verify/macos.txt new file mode 100644 index 000000000..e541ad530 --- /dev/null +++ b/source/installation/verify/macos.txt @@ -0,0 +1,45 @@ +.. _c2c-verify-signatures-macos: + +================================ +Verify mongosync Binary on macOS +================================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: tutorial + +.. include:: /includes/verify-signatures-intro.rst + +The ``mongosync`` ``.zip`` download for macOS is notarized. This page +describes how to use ``codesign`` to verify the integrity of the +unzipped ``mongosync`` binary. + +Before you Begin +---------------- + +.. include:: /includes/verify-signatures-before-you-begin.rst + +Steps +----- + +To verify the ``mongosync`` binary, run: + +.. code-block:: sh + + codesign -dv --verbose=4 + +If the binary is signed by MongoDB, the output includes the following +information: + +.. code-block:: sh + :copyable: false + + Authority=Developer ID Application: MongoDB, Inc. (4XWMY46275) + Authority=Developer ID Certification Authority + Authority=Apple Root CA diff --git a/source/installation/verify/rpm.txt b/source/installation/verify/rpm.txt new file mode 100644 index 000000000..aa48933d2 --- /dev/null +++ b/source/installation/verify/rpm.txt @@ -0,0 +1,54 @@ +.. _c2c-verify-signatures-rpm: + +========================== +Verify RPM Packages (RHEL) +========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: tutorial + +.. include:: /includes/verify-signatures-intro.rst + +This page describes how to verify ``.rpm`` packages on RHEL operating +systems. + +Before you Begin +---------------- + +.. include:: /includes/verify-signatures-before-you-begin.rst + +Steps +----- + +.. procedure:: + :style: normal + + .. step:: Import the MongoDB Server Tools public key in gpg and rpm + + .. code-block:: sh + + curl https://pgp.mongodb.com/server-Tools.asc | gpg --import + + rpm --import https://pgp.mongodb.com/server-Tools.asc + + .. include:: /includes/verification-gpg-results.rst + + .. step:: Verify the rpm file + + .. code-block:: sh + + rpm --checksig + + If the file is signed, the command returns: + + .. code-block:: sh + :copyable: false + + digests signatures OK