Skip to content

Commit bbb682c

Browse files
sarahsimperssarahsimpers
authored
(DOCSP-36718) Confirm signatures on Atlas CLI packages (#304) (#341)
* (DOCSP-36718) Confirm signatures on Atlas CLI packages * Adds page to TOC and install page * Edits * Adds Docker steps * Adds Windows steps * Release notes, small edits * Updates windows steps * cleanup * Copy review changes * Copy review changes
1 parent bec81d3 commit bbb682c

File tree

3 files changed

+255
-0
lines changed

3 files changed

+255
-0
lines changed

‎source/atlas-cli-changelog.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,10 @@ Released 8 February 2024
7676
- Adds support for :ref:`{+avs+} for Local Deployments
7777
<atlas-cli-deploy-fts>`.
7878
- Adds support to rename teams.
79+
- :ref:`Signs the Linux binaries <verify-packages-linux>` with PGP.
80+
- :ref:`Signs the Windows binaries <verify-packages-windows>` with
81+
garasign.
82+
- :ref:`Signs the Docker image <verify-packages-docker>` with Cosign.
7983

8084
.. _atlas-cli-1.14.2:
8185

‎source/install-atlas-cli.txt

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ Install or Update the {+atlas-cli+}
2121
Install the {+atlas-cli+} to quickly provision and manage |service|
2222
{+database-deployments+} from the terminal.
2323

24+
To verify packages before installation, see :ref:`verify-packages`.
25+
2426
Install the {+atlas-cli+}
2527
-------------------------
2628

@@ -637,3 +639,4 @@ Take the Next Steps
637639
:titlesonly:
638640

639641
/compatibility
642+
Verify Packages </verify-packages>

‎source/verify-packages.txt

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
.. _verify-packages:
2+
3+
==============================================
4+
Verify the Integrity of {+atlas-cli+} Packages
5+
==============================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
.. facet::
16+
:name: genre
17+
:values: tutorial
18+
19+
The {+atlas-cli+} release team digitally signs all software packages and
20+
container images to certify that a particular package is valid and
21+
unaltered. Before you install the {+atlas-cli+} packages for Linux,
22+
Windows, or Docker, you should validate the
23+
package using the provided PGP signature, SHA-256 checksum, or
24+
`Cosign <https://github.com/sigstore/cosign>`__ information.
25+
26+
.. _verify-packages-linux:
27+
28+
Verify Linux Packages
29+
---------------------
30+
31+
MongoDB signs each release branch with a different PGP key. The public
32+
key files for the lastest {+atlas-cli+} release is available for
33+
download from the `key server <https://pgp.mongodb.com/>`_.
34+
35+
The following procedure verifies the {+atlas-cli+} package against its
36+
PGP key.
37+
38+
.. procedure::
39+
:style: normal
40+
41+
.. step:: Download the {+atlas-cli+} installation file.
42+
43+
Download the {+atlas-cli+} binaries from the
44+
`MongoDB Download Center
45+
<https://www.mongodb.com/try/download/atlascli>`__
46+
based on your Linux environment. Click :guilabel:`Copy link` and
47+
use the URL in the following instructions.
48+
49+
For example, to download the ``{+atlas-cli-version+}`` release
50+
for Linux through the shell, run the following command:
51+
52+
.. code-block::
53+
54+
curl -LO https://fastdl.mongodb.org/mongocli/mongodb-atlas-cli_{+atlas-cli-version+}_linux_x86_64.tar.gz
55+
56+
.. step:: Download the public signature file.
57+
58+
Run the following command to download the file:
59+
60+
.. code-block::
61+
62+
curl -LO https://fastdl.mongodb.org/mongocli/mongodb-atlas-cli_{+atlas-cli-version+}_linux_x86_64.tar.gz.sig
63+
64+
.. step:: Download and import the key file.
65+
66+
Run the following command to download and import the key file:
67+
68+
.. io-code-block::
69+
:copyable: true
70+
71+
.. input::
72+
73+
curl -LO https://pgp.mongodb.com/atlas-cli.asc
74+
gpg --import atlas-cli.asc
75+
76+
.. output::
77+
78+
gpg: key <key-value-short>: public key "Atlas CLI Release Signing Key <[email protected]>" imported
79+
gpg: Total number processed: 1
80+
gpg: imported: 1
81+
82+
.. step:: Verify the {+atlas-cli+} installation file.
83+
84+
Run the following command to verify the installation file:
85+
86+
.. io-code-block::
87+
:copyable: true
88+
89+
.. input::
90+
91+
gpg --verify mongodb-atlas-cli_{+atlas-cli-version+}_linux_x86_64.tar.gz.sig mongodb-atlas-cli_{+atlas-cli-version+}_linux_x86_64.tar.gz
92+
93+
.. output::
94+
95+
gpg: Signature made Thu Mar 14 08:25:00 2024 EDT
96+
gpg: using RSA key <key-value-long>
97+
gpg: Good signature from "Atlas CLI Release Signing Key <[email protected]>" [unknown]
98+
99+
If the package is properly signed, but you don't currently trust
100+
the signing key, ``gpg`` also returns the following message :
101+
102+
.. code-block::
103+
104+
gpg: WARNING: This key is not certified with a trusted signature!
105+
gpg: There is no indication that the signature belongs to the owner.
106+
107+
.. _verify-packages-windows:
108+
109+
Verify Windows Packages
110+
-----------------------
111+
112+
The following procedure verifies the {+atlas-cli+} package against its
113+
SHA-256 key.
114+
115+
.. procedure::
116+
:style: normal
117+
118+
.. step:: Download the {+atlas-cli+} installation file.
119+
120+
Download the {+atlas-cli+} ``.msi`` or ``.zip`` file from the
121+
`MongoDB Download Center
122+
<https://www.mongodb.com/try/download/atlascli>`__ or
123+
`Github <https://github.com/mongodb/mongodb-atlas-cli/releases>`__.
124+
125+
.. step:: Save the public signature.
126+
127+
a. Download the ``checksums.txt`` file for the
128+
release from `Github
129+
<https://github.com/mongodb/mongodb-atlas-cli/releases>`__,
130+
which contains the SHA-256 key for each file. For example, for
131+
version {+atlas-cli-version+},
132+
download the `{+atlas-cli-version+} checksums.txt file
133+
<https://github.com/mongodb/mongodb-atlas-cli/releases/download/atlascli%2Fv{+atlas-cli-version+}/checksums.txt>`__.
134+
#. Open the ``checksums.txt`` file and copy the text listed to
135+
the left of the package you downloaded.
136+
For example, if you downloaded ``mongodb-atlas-cli_{+atlas-cli-version+}_windows_x86_64.zip``,
137+
copy the text to the left of
138+
``mongodb-atlas-cli_{+atlas-cli-version+}_windows_x86_64.zip``.
139+
This value is the SHA-256 key value.
140+
#. Save the SHA-256 key value in a ``.txt`` file named ``atlas-cli-key``
141+
in your Downloads folder.
142+
143+
.. step:: Compare the signature file to the {+atlas-cli+} installer hash.
144+
145+
Run the Powershell command to verify the package based on the
146+
file you downloaded.
147+
148+
If you downloaded
149+
``mongodb-atlas-cli_{+atlas-cli-version+}_windows_x86_64.zip``,
150+
run the following command:
151+
152+
.. io-code-block::
153+
:copyable: true
154+
155+
.. input::
156+
157+
$sigHash = (Get-Content $Env:HomePath\Downloads\atlas-cli-key.txt | Out-String).SubString(0,64).ToUpper(); `
158+
$fileHash = (Get-FileHash $Env:HomePath\Downloads\mongodb-atlas-cli_{+atlas-cli-version+}_windows_x86_64.zip).Hash.Trim(); `
159+
echo $sigHash; echo $fileHash; `
160+
$sigHash -eq $fileHash
161+
162+
.. output::
163+
164+
<key-value-from-signature-file>
165+
<key-value-from-downloaded-package>
166+
True
167+
168+
If you downloaded
169+
``mongodb-atlas-cli_{+atlas-cli-version+}_windows_x86_64.msi``,
170+
run the following command:
171+
172+
.. io-code-block::
173+
:copyable: true
174+
175+
.. input::
176+
177+
$sigHash = (Get-Content $Env:HomePath\Downloads\atlas-cli-key.txt | Out-String).SubString(0,64).ToUpper(); `
178+
$fileHash = (Get-FileHash $Env:HomePath\Downloads\mongodb-atlas-cli_{+atlas-cli-version+}_windows_x86_64.msi).Hash.Trim(); `
179+
echo $sigHash; echo $fileHash; `
180+
$sigHash -eq $fileHash
181+
182+
.. output::
183+
184+
<key-value-from-signature-file>
185+
<key-value-from-downloaded-package>
186+
True
187+
188+
The command returns the key value from the signature file, the
189+
key value from the downloaded package, and ``True`` if the two
190+
values match.
191+
192+
If the two values match, the {+atlas-cli+} binary is verified.
193+
194+
.. _verify-packages-docker:
195+
196+
Verify Docker Container Images
197+
------------------------------
198+
199+
You can use `Cosign <https://github.com/sigstore/cosign>`__ to verify
200+
MongoDB's signature for {+atlas-cli+} container images.
201+
202+
To verify MongoDB's container signature, perform the following steps:
203+
204+
.. procedure::
205+
:style: normal
206+
207+
.. step:: Download and install Cosign.
208+
209+
**Example: MacOS**
210+
211+
.. code-block::
212+
213+
brew install cosign
214+
215+
For full installation instructions, see `Cosign
216+
<https://github.com/sigstore/cosign>`__.
217+
218+
.. step:: Download the {+atlas-cli+} container image's public key
219+
220+
.. code-block::
221+
222+
curl https://cosign.mongodb.com/atlas-cli.pem > atlas-cli.pem
223+
224+
.. step:: Verify the signature.
225+
226+
Run the following command to verify the signature by tag:
227+
228+
.. io-code-block::
229+
:copyable: true
230+
231+
.. input::
232+
233+
COSIGN_REPOSITORY=docker.io/mongodb/signatures cosign verify --private-infrastructure --key=./atlas-cli.pem docker.io/mongodb/atlas:latest
234+
235+
.. output::
236+
237+
Verification for index.docker.io/mongodb/atlas:latest --
238+
The following checks were performed on each of these signatures:
239+
- The cosign claims were validated
240+
- The signatures were verified against the specified public key
241+
242+
[{"critical":{"identity":{"docker-reference":"index.docker.io/mongodb/atlas"},"image":{"docker-manifest-digest":"sha256:<key-value>"},"type":"cosign container image signature"},"optional":null}]
243+
244+
245+
246+
247+
248+

0 commit comments

Comments
 (0)