Skip to content

Commit ae3c635

Browse files
jeff-allen-mongojeff-allen-mongo
authored
DOCSP-45728-verify-packages (#191)
* DOCSP-45728-verify-packages * build error * first draft * fix ref * fix shell reference * wording * rework macos page * title tweaks * wording * nit
1 parent df16d5e commit ae3c635

File tree

10 files changed

+340
-2
lines changed

10 files changed

+340
-2
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
66

77
toc_landing_pages = [
88
"/installation",
9+
"/installation/verify",
910
"/bsondump",
1011
"/mongodump",
1112
"/mongoexport",
@@ -88,4 +89,4 @@ targets = [
8889
variant = "warning"
8990
value = """\
9091
MongoDB Command Line Database Tool 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.
91-
"""
92+
"""

‎source/includes/verification-gpg-results.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
If the key imports successfully, the command returns:
2+
3+
.. code-block:: sh
4+
:copyable: false
5+
6+
gpg: key 3132835C1D925D5B: public key "MongoDB CLI Tools Release Signing Key <[email protected]>" imported
7+
gpg: Total number processed: 1
8+
gpg: imported: 1
9+
10+
If you have previously imported the key, the command returns:
11+
12+
.. code-block:: sh
13+
:copyable: false
14+
15+
gpg: key 3132835C1D925D5B: "MongoDB CLI Tools Release Signing Key <[email protected]>" not changed
16+
gpg: Total number processed: 1
17+
gpg: unchanged: 1

‎source/includes/verify-signatures-before-you-begin.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
If you don't have the MongoDB Database Tools installed, download the
2+
Database Tools binaries from the `Download Center
3+
<https://www.mongodb.com/try/download/database-tools?jmp=docs>`__.

‎source/includes/verify-signatures-intro.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
The MongoDB release team digitally signs Database Tools packages to
2+
certify that packages are a valid and unaltered MongoDB release. Before
3+
you install the Database Tools, you can use the digital signature to
4+
validate the package.

‎source/installation.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,4 +76,4 @@ platforms:
7676
Install on Linux </installation/installation-linux>
7777
Install on macOS </installation/installation-macos>
7878
Install on Windows </installation/installation-windows>
79-
79+
Verify Packages </installation/verify>

‎source/installation/verify.txt

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
.. _db-tools-verify-packages:
2+
3+
===========================================
4+
Verify Integrity of Database Tools Packages
5+
===========================================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: tutorial
16+
17+
.. include:: /includes/verify-signatures-intro.rst
18+
19+
To learn how to verify Database Tools packages, see the corresponding
20+
page for your verification method:
21+
22+
- :ref:`db-tools-verify-signatures-macos`
23+
24+
- :ref:`db-tools-verify-signatures-gpg`
25+
26+
- :ref:`db-tools-verify-signatures-rpm`
27+
28+
- :ref:`db-tools-verify-signatures-windows`
29+
30+
.. toctree::
31+
:titlesonly:
32+
33+
macOS </installation/verify/macos>
34+
Linux </installation/verify/gpg>
35+
RHEL </installation/verify/rpm>
36+
Windows </installation/verify/windows>

‎source/installation/verify/gpg.txt

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
.. _db-tools-verify-signatures-gpg:
2+
3+
================================
4+
Verify Packages with GPG (Linux)
5+
================================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: tutorial
16+
17+
.. include:: /includes/verify-signatures-intro.rst
18+
19+
This page describes how to use GPG to verify Linux packages.
20+
21+
Before you Begin
22+
----------------
23+
24+
.. include:: /includes/verify-signatures-before-you-begin.rst
25+
26+
Steps
27+
-----
28+
29+
.. procedure::
30+
:style: normal
31+
32+
.. step:: Import the MongoDB Database Tools public key
33+
34+
.. code-block:: sh
35+
36+
curl https://pgp.mongodb.com/server-Tools.asc | gpg --import
37+
38+
.. include:: /includes/verification-gpg-results.rst
39+
40+
.. step:: Download the MongoDB Database Tools public signature
41+
42+
To download the Database Tools public signature, run the following
43+
command, replacing the placeholder values with your platform,
44+
architecture, and Database Tools version:
45+
46+
.. code-block:: sh
47+
48+
curl -LO https://s3.amazonaws.com/downloads.mongodb.org/tools/db/mongodb-database-tools-<platform>-<architecture>-<version>.tgz.sig
49+
50+
.. example::
51+
52+
The following URL contains the signature file for Database
53+
Tools on Amazon Linux 2, version {+release+}:
54+
55+
``https://s3.amazonaws.com/downloads.mongodb.org/tools/db/mongodb-database-tools-amazon2-x86_64-{+release+}.tgz.sig``
56+
57+
.. step:: Verify the package
58+
59+
.. code-block:: sh
60+
61+
gpg --verify <path_to_signature_file> <path_to_db_tools_executable>
62+
63+
If the package is signed by MongoDB, the command returns:
64+
65+
.. code-block:: sh
66+
:copyable: false
67+
68+
gpg: Signature made Wed 19 Feb 2025 02:19:15 PM EST
69+
gpg: using RSA key D4E45C292A5C94962F0D10E13132835C1D925D5B
70+
gpg: Good signature from "MongoDB CLI Tools Release Signing Key <[email protected]>" [unknown]
71+
72+
If the package is signed but the signing key is not added to your
73+
local ``trustdb``, the command returns:
74+
75+
.. code-block:: sh
76+
:copyable: false
77+
78+
gpg: WARNING: This key is not certified with a trusted signature!
79+
gpg: There is no indication that the signature belongs to the owner.
80+
81+
If the package is not properly signed, the command returns an
82+
error message:
83+
84+
.. code-block:: sh
85+
:copyable: false
86+
87+
gpg: Signature made Wed 19 Feb 2025 02:19:15 PM EST
88+
gpg: using RSA key D4E45C292A5C94962F0D10E13132835C1D925D5B
89+
gpg: BAD signature from "MongoDB CLI Tools Release Signing Key <[email protected]>" [unknown]

‎source/installation/verify/macos.txt

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
.. _db-tools-verify-signatures-macos:
2+
3+
=====================
4+
Verify macOS Binaries
5+
=====================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: tutorial
16+
17+
.. include:: /includes/verify-signatures-intro.rst
18+
19+
The Database Tools ``.zip`` download for macOS is notarized. This page
20+
describes how to use ``codesign`` to verify the integrity of individual
21+
Database Tools binaries.
22+
23+
Before you Begin
24+
----------------
25+
26+
.. include:: /includes/verify-signatures-before-you-begin.rst
27+
28+
Steps
29+
-----
30+
31+
To verify a Database Tools binary, run:
32+
33+
.. code-block:: sh
34+
35+
codesign -dv --verbose=4 <path_to_binary>
36+
37+
For example, the following command verifies the ``mongorestore`` binary
38+
in the ``/usr/local/bin/`` folder:
39+
40+
.. code-block:: sh
41+
42+
codesign -dv --verbose=4 /usr/local/bin/mongorestore
43+
44+
If the binary is signed by MongoDB, the output includes the following
45+
information:
46+
47+
.. code-block:: sh
48+
:copyable: false
49+
50+
Authority=Developer ID Application: MongoDB, Inc. (4XWMY46275)
51+
Authority=Developer ID Certification Authority
52+
Authority=Apple Root CA

‎source/installation/verify/rpm.txt

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
.. _db-tools-verify-signatures-rpm:
2+
3+
==========================
4+
Verify RPM Packages (RHEL)
5+
==========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: tutorial
16+
17+
.. include:: /includes/verify-signatures-intro.rst
18+
19+
This page describes how to verify ``.rpm`` packages on RHEL operating
20+
systems.
21+
22+
Before you Begin
23+
----------------
24+
25+
.. include:: /includes/verify-signatures-before-you-begin.rst
26+
27+
Steps
28+
-----
29+
30+
.. procedure::
31+
:style: normal
32+
33+
.. step:: Import the MongoDB Database Tools public key in gpg and rpm
34+
35+
.. code-block:: sh
36+
37+
curl https://pgp.mongodb.com/server-Tools.asc | gpg --import
38+
39+
rpm --import https://pgp.mongodb.com/server-Tools.asc
40+
41+
.. include:: /includes/verification-gpg-results.rst
42+
43+
.. step:: Verify the rpm file
44+
45+
.. code-block:: sh
46+
47+
rpm --checksig <path_to_db_tools_rpm_file>
48+
49+
If the file is signed, the command returns:
50+
51+
.. code-block:: sh
52+
:copyable: false
53+
54+
<path_to_db_tools_rpm_file> digests signatures OK

‎source/installation/verify/windows.txt

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
.. _db-tools-verify-signatures-windows:
2+
3+
=======================
4+
Verify Windows Packages
5+
=======================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: tutorial
16+
17+
.. include:: /includes/verify-signatures-intro.rst
18+
19+
This page describes how to verify Windows ``.msi`` packages.
20+
21+
Before you Begin
22+
----------------
23+
24+
.. include:: /includes/verify-signatures-before-you-begin.rst
25+
26+
Steps
27+
-----
28+
29+
To verify the Database Tools package on Windows, you can use one of these
30+
methods:
31+
32+
- :ref:`db-tools-verify-signatures-windows-command-line`
33+
34+
- :ref:`db-tools-verify-signatures-windows-check-properties`
35+
36+
.. _db-tools-verify-signatures-windows-command-line:
37+
38+
Verify Packages with PowerShell
39+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40+
41+
To verify Windows packages with PowerShell, run:
42+
43+
.. code-block:: sh
44+
45+
powershell Get-AuthenticodeSignature -FilePath <path_to_db_tools_msi>
46+
47+
If the package is signed, the command returns:
48+
49+
.. code-block:: sh
50+
:copyable: false
51+
52+
SignerCertificate Status Path
53+
----------------- ------ ----
54+
A5BBE2A6DA1D2A... Valid <path_to_db_tools_msi>
55+
56+
.. _db-tools-verify-signatures-windows-check-properties:
57+
58+
Verify Packages by Checking Properties
59+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
60+
61+
.. procedure::
62+
:style: normal
63+
64+
.. step:: Open the properties for your Database Tools package
65+
66+
.. step:: Check the package's digital signatures
67+
68+
In the properties window, open the :guilabel:`Digital Signatures`
69+
tab.
70+
71+
If the package is properly signed, the Embedded Signatures show
72+
these properties:
73+
74+
.. list-table::
75+
:header-rows: 1
76+
77+
* - Name of signer
78+
- Digest algorithm
79+
- Timestamp
80+
* - MongoDB, Inc.
81+
- sha256
82+
- <Timestamp>

0 commit comments

Comments
 (0)