Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Platform-releng/How to check integrity of downloads"

m (/* Making use of the signed files of checksums - saving partial draft)
m (/* Making use of the signed files of checksums)
Line 37: Line 37:
 
=== Making use of the signed files of checksums ===  
 
=== Making use of the signed files of checksums ===  
  
Beginning with Neon, in addition to the individual "*.sha512" and "*.sha256" files we also make all checksums available in a single text file. These are linked from the download page. The link is named similar to "SHA515 Checksums" and points to a file that is named similar to "/checksum/eclipse-<buildId>-SHASUMS512". In addition -- and this is the advantage of making available as one file -- there is a matching file named the same, but ending with ".gpg".
+
Beginning with Neon, in addition to the individual "*.sha512" and "*.sha256" files we also make all checksums available in a single text file. These are linked from the download page for each build of Eclipse and Equinox. The link is named similar to "SHA515 Checksums" and points to a file that is named similar to  
  
The 'gpg' files are a detached signature file of its plain-text counterpart. The idea is that validity and authenticity of the plain-text file can be verified using GPG, and then once that file is trusted, the checksums in the file can be trusted to be authentic and valid checksums for the files it lists.  
+
<eclipse-download-URL>/checksum/eclipse-<buildId>-SHASUMS512
 +
or for Equinox
 +
 
 +
<equinox-download-URL>/checksum/equinox-<buildId>-SHASUMS512
 +
 
 +
In addition -- and this is the reason for making them all available in one file -- there is a matching file that is named the same as above, but ending with ".gpg". This GPG file can be used to confirm the integrity and authenticity of the checksum file.
 +
 
 +
The 'gpg' files are a detached signature file of its plain-text counterpart. The idea is that validity and authenticity of the plain-text file can be verified using GPG, and then once that file is trusted, the checksums in the "checksum files" can be trusted to be authentic and valid checksums for the files it lists.
  
 
== Example of using GPG with the checksum files ==  
 
== Example of using GPG with the checksum files ==  

Revision as of 10:33, 18 May 2016

Verifying integrity of downloads from the Eclipse Platform Project and Equinox

First and foremost, the majority of users should see, understand, and follow the instructions at How to check the integrity of downloads from the Eclipse Foundation. Those instructions cover the majority of cases and is the best instructions for all general users.

But, if you are a committer, release engineer, or even a power user, some of the following information might be important to know. (The following information primarily applies to the Neon (4.6) release, but some applies to older releases too.)

Downloadable artifacts specifically from the Eclipse or Equinox Projects have an associated file named the same as the artifact file but ending with ".sha512" or ".sha256" and these checksum files are in a directory named 'checksum'. We recommend these files for programmatic verification as they are too long to visually verify. We recommend the SHA512 checksums be used and provide the SHA256 checksums simply because other sites provide them so some users may already have automated methods in place to make use of those.

An example using 'http'

As an example, you can download the following artifact, say using wget

 wget -O eclipse-SDK-4.5.2-linux-gtk-x86_64.tar.gz  http://download.eclipse.org/eclipse/downloads/drops4/R-4.5.2-201602121500/eclipse-SDK-4.5.2-linux-gtk-x86_64.tar.gz 

then you would also want to download the corresponding ".sha512" file to the same location.

  wget -O eclipse-SDK-4.5.2-linux-gtk-x86_64.tar.gz.sha515 http://download.eclipse.org/eclipse/downloads/drops4/R-4.5.2-201602121500/checksum/eclipse-SDK-4.5.2-linux-gtk-x86_64.tar.gz.sha512

Then, to verify the integrity of the downloaded artifact you would run

  sha512sum eclipse-SDK-4.5.2-linux-gtk-x86_64.tar.gz.sha515

If the artifact downloaded correctly, you would see a response from above command of

   eclipse-SDK-4.5.2-linux-gtk-x86_64.tar.gz: OK

Limitations using unencrypted connections and how to improve

The "download server" does not have "https://" protocol available since it would be expensive to encrypt all the large artifacts from it (See bug 435426). The problem with using "http://" is that in general you can not count on the authenticity of the connection. While it would be extremely rare, and has never been reported for "eclipse.org", in principle, someone could manage to stage a "man in the middle" attack and deliver some sort of tainted artifact and likewise deliver their own checksum which would match the tainted artifact. [Note: as been said many times, security is always a matter of degree. It is still a good idea to always "check integrity" especially, for example, if downloading the artifact from a mirror, where it might be easier to taint the artifacts, and then get the checksums from 'download.eclipse.org' which would require a more sophisticated manipulation to "fool" you or your network.]

Release engineers, building on "build.eclipse.org", can get direct file access to the artifacts and checksums and then the checksum check is secure (authentic) and can be trusted to simply confirm the copy was done intact and the artifact has not been changed since it was built.

Committers can get the artifact using unencrypted methods, and then get the checksum using 'scp', or rsync over an SSH connection, to be sure of the authenticity of their connection and hence the checksum. For example,

 scp <committer_id>@build.eclipse.org://home/data/httpd/download.eclipse.org/eclipse/downloads/drops4/R-4.5.2-201602121500/checksum/eclipse-SDK-4.5.2-linux-gtk-x86_64.tar.gz.sha512  .

Making use of the signed files of checksums

Beginning with Neon, in addition to the individual "*.sha512" and "*.sha256" files we also make all checksums available in a single text file. These are linked from the download page for each build of Eclipse and Equinox. The link is named similar to "SHA515 Checksums" and points to a file that is named similar to

<eclipse-download-URL>/checksum/eclipse-<buildId>-SHASUMS512

or for Equinox

<equinox-download-URL>/checksum/equinox-<buildId>-SHASUMS512 

In addition -- and this is the reason for making them all available in one file -- there is a matching file that is named the same as above, but ending with ".gpg". This GPG file can be used to confirm the integrity and authenticity of the checksum file.

The 'gpg' files are a detached signature file of its plain-text counterpart. The idea is that validity and authenticity of the plain-text file can be verified using GPG, and then once that file is trusted, the checksums in the "checksum files" can be trusted to be authentic and valid checksums for the files it lists.

Example of using GPG with the checksum files

[more to come]

Deprecated methods for Eclipse Platform Project and Equinox

For the Luna release (June, 2014) the Eclipse Platform project and Equinox moved to provide SHA512 checksums for to check download integrity, since "md5" is known to be vulnerable, and sha1 is in theory vulnerable (see bug 420010#c1 for references). Hence the following methods should be considered "deprecated" and will eventually disappear (follow bug 423714 for details). For a transition period, the md5 and sha1 checksums are still available from same location that they used to be, namely '<buildURL>/checksums/<filname>(.md5|.sha1)' so those with automated scripts won't break suddenly, but only the SHA512 is displayed as a link on download page, and is the preferred method and that everyone should move to use that, in automated scripts. All that said, the following instructions may still apply to other downloads from other areas of the Eclipse Foundation, which have not yet moved to SHA-2 or to older builds from Eclipse or Equinox (there is currently no plan to retroactively change checksum files).

Downloads can be verified using md5sum or sha1sum, a Unix command line tool provided in the GNU Coreutils package. Windows binary versions are available such as from Cygwin or other packages that can be found by searching the internet.

  • Most downloads have an associated link "(md5)" to a *.md5 file containing its MD5 checksum and another link "(sha1)" to a *.sha1 file containing its SHA1 checksum. Download these files, such as from the main Eclipse Foundation's packages downloads page (the checksums are available on the page where you select a mirror, but the checksums come directly from "eclipse.org", not the mirror). Put those checksum files into the same directory as the downloaded archive (zip or tar.gz) file.
  • Using the tools described at beginning of this page, execute a command such as "md5sum -c <zipfilename>.md5" or "sha1sum -c <zipfilename>.sha1". The result "<zipfilename>: OK" means the downloaded file is complete and intact.

Back to the top