MDHashTool Help Page

Introduction
Copying and License Information
Checking Download File Integrity
Generating Digests for Files and Text
Link Fingerprints
Preferences
Uninstalling MDHashTool


Introduction

Message Digest Hash Tool is a Firefox extension which can be used to compute Message Digests for files and/or text strings using various algorithms (currently MD5 and SHA-1). These digests, sometimes referred to as "digital fingerprints", are commonly used to verify that files have not been corrupted or tampered with. MDHashTool makes it easier for Firefox users to check the integrity of their downloads and generate digests for files they want to share.

Hash generation is based on the md5sum/sha1sum backend modules ported from the GNU Core Utilities package with as little modification as possible. MD Hash Tool replaces the command line interface of those GNU utilities with a graphical user interface that can be opened from the browser Tools menu or the downloads window context menu.

Other features:

Feel free to offer ideas and suggestions - your feedback is welcome. Contact me directly at charlesm@dourlad.com or visit the MDHashTool homepage listed below. You may report bugs via the MozDev Bugzilla system or by emailing me.

MDHashTool homepage:
http://mdhashtool.mozdev.org



Copying and License Information

MDHashTool - Message Digest (MD5, SHA-1, etc.) tool
Copyright (c) 2005  Charles Melhorn

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Or see the GNU web site at: http://www.gnu.org



Checking Download File Integrity

You will often find an MD5 or SHA1 digest value (typically represented as a string of 32 hexadecimal values) supplied along with files you download off of the internet. These digests, sometimes referred to as "digital fingerprints", are commonly used to check files for corruption or tampering. By comparing the reference digest value provided by the file originator to the actual value computed for your copy of the file and verifying that they match, you can be reasonably certain that the file has not been altered. MDHashTool simplifies this process of comparing computed and reference checksums for downloads by adding a new item to the download manager context menu.

To check files downloaded using Firefox, open the download manager (Tools -> Downloads). Select the file of interest, right-click on it, and choose "Check Digest" from the context menu:

download manager context menu


This will compute a digest for the file and open the Check File Digest dialog:

Check file dialog displays computed digest


By default, MDHashTool will compute an MD5 digest when the window is first opened (see Preferences to change this behavior). You can copy the computed digest for your file to the clipboard by right-clicking on the digest value and selecting "copy" from the context menu. If you need to check the SHA1 digest for your file, select "SHA1" from the Algorithm drop down box to compute and display the proper digest.

To verify the file's integrity, you'll need to compare the computed digest with the reference digest. If the file was downloaded from a URL that contains a valid link fingerprint, this will be done automatically when the dialog is first opened. Otherwise, copy the reference digest value from the website distributing the file, and paste (or type) it into the Reference Digest textbox. If the values are equal, the match indicator will turn green and display "match":

match indicator turns green if digest strings are equal

If the digest values are not equal, the match indicator will turn red red icon with cross indicates that digest strings are not equal and display the words "no match". Before you conclude that the downloaded file is corrupt, be sure that you copied the reference value correctly and are comparing the same type of digest (MD5, SHA1, etc.). In addition, verify that the reference digest supplied by the file originator is up to date.

Note that file digests provide no assurance about the file author's identity (unlike files signed with a public certificate) or intentions. They merely indicate with a high degree of certainty that a file has not been altered from the point when the reference digest was generated to the point when you received it.

To check downloaded files that are not accessible from the download manager (because they've been moved, renamed, removed from the downloads list, or were downloaded with other programs), see the following section Generating Digests for Files and Text.


Generating Digests for Files and Text

MDHashTool can be used to compute Message Digests for files and/or text strings using various algorithms (currently MD5 and SHA-1). These digests, sometimes referred to as "digital fingerprints", are commonly used to verify that files have not been corrupted or tampered with. To generate digests for files you wish to distribute or verify, open the MDHashTool main window from the browser Tools menu (Tools -> MD Hash Tool).

Use the MDHashTool main dialog to generate digests


The input type will be set to "file" by default. Select the desired digest algorithm from the dropdown box, and click the "browse..." button to open the file selection dialog. You'll need to specify the file via this dialog - you cannot type directly in the filename textbox. Once the file is selected, click the "compute digest" button. The resulting digest value will be displayed in the Message Digest field at the top of the window. To change the algorithm, select a new type from the dropdown box and click "compute digest" again.

If you prefer, you can drag a file from your file manager or desktop (on systems that support drag and drop) to the MDHashTool window. When a file is dropped on the window, the input type will automatically be set to file and the digest will be computed using the currently selected algorithm.

main dialog after digest has been computed

You can copy the computed digest for your file to the clipboard by right-clicking on the digest value and selecting "copy" from the context menu. To generate digests for text strings, follow the procedure described above, but set the input type to "text" and enter a string in the textbox. You can also drag text selections from other applications to the MDHashTool window. When the text is dropped, the input type will automatically be set to "text" and the digest will be computed using the currently selected algorithm.

To compare the computed digest against a reference value, open the Compare Message Digests dialog by selecting "compare..." from the digest value context menu.

Use the Compare Message Digests dialog to compare computed digest to reference value


Copy the reference digest value from the website distributing the file, and paste (or type) it into the Reference Digest textbox. If the values are equal, the match indicator will turn green and display "match":

Match icon turns green to indicate that digest values are equal

If the digest values are not equal, the match indicator will turn red red icon with cross indicates that digest strings are not equal and display the words "no match". Before you conclude that the file is corrupt, be sure that you copied the reference value correctly and are comparing the same type of digest (MD5, SHA1, etc.). In addition, verify that the reference digest supplied by the file originator is up to date.



Link Fingerprints

"Link Fingerprints" is a scheme originally proposed by Gervase Markham for embedding checksum information in links pointing to files intended for distribution. Binding a file's checksum to its URL allows a recipient to easily, and potentially automatically, verify that his downloaded copy of a file matches the original, even if the file is not being hosted on the originator's own site (e.g. files downloaded from mirrors). By comparing the reference checksum value included in the URL to the actual value computed for your copy of the file and verifying that they match, you can be reasonably certain that the file has not been altered.

An example of such a URL is

http://downloads.mozdev.org/mdhashtool/mdhashtool-0.3.xpi#!md5!b3187251c16675ac7d20bb762ad53967

where the "link fingerprint" component,  #!md5!b3187251c16675ac7d20bb762ad53967, consists of the following elements:

#! link fingerprint identifier
md5 checksum algorithm type
! separator character
b3187251c16675ac7d20bb762ad53967 hexadecimal checksum string


By default, MDHashTool will indicate links which contain a valid "link fingerprint" by displaying a fingerprint icon

mdhashtool-0.3.xpithis is a checksum-enhanced link

after the link text or image. Menu items for viewing a link's fingerprint information and for copying the embedded checksum to the clipboard will appear in the context menu when right-clicking on such links.

Link Fingerprint context menu items

Downloads which originate from URLs containing valid link fingerprints can be automatically verified using the checksum information embedded in the link. When this feature is enabled (on by default), MDHashTool will compute the checksum for a downloaded file using the algorithm specified in the link fingerprint and compare it to the expected value. If the computed value doesn't match the expected value included in the corresponding URL, an alert dialog will be displayed:

Automated Checksum Verification Failed dialog

Note that this message simply indicates that there is a mismatch between the computed checksum for the file and the expected value embedded in the link. Before you conclude that the file is corrupt or has been tampered with, you may wish to verify that the link fingerprint information supplied by the file originator was generated correctly and is up to date.

When enabled, this Auto Checksum Verification occurs autonomously upon download completion: MDHashTool detects when a file has been downloaded from a source URL that contains a valid link fingerprint, and performs the checksum comparison without further prompting. In other words, you simply save a file in the usual manner(by selecting "Save link as...", or, in some cases, by loading the URL via the address bar), and the checksum verification will be done automatically when applicable. Obviously, this will only be for downloads originating from LF-enhanced links.

To disable the "link fingerprint" icon display or the automated checksum verification feature, modify the appropriate setting via the preferences dialog. Refer to Preferences for details.



Preferences

You can bring up the preferences dialog by clicking the Options button at the bottom of the main MDHashTool window. Modify the settings as desired, then press the 'OK' button to save the changes. If you don't wish to save your changes, use the 'cancel' button to close the preferences dialog.

The following preference options are available:

Preference
 Default Value
 Description
default hash algorithm
 MD5
 Determines the default value for the hash algorithm drop down box in the main MDHashTool window and in the download Check Digest dialog. The type of digest that is computed when the download Check Digest dialog first opens is also controlled by this value.
use LF icon
 true
 If true, an icon will be displayed for any text or image link which contains a valid Link Fingerprint.
auto checksum
 true
 Enables/disables automated verification for downloads which originate from checksum-enhanced URLs (see Link Fingerprints)

MDHashTool preferences use the preference node "extensions.mdht." and are stored in the "prefs.js" file (along with the other Firefox preferences) in the user's profile directory. On Windows systems, this directory is usually Documents and Settings\<user_name>\Application Data\Mozilla\Profiles\<profile name>\<random string> or something similar. On Linux, it would be ~/.mozilla.


Uninstalling

Use the Firefox extension manager to uninstall MD Hash Tool. Open the extension manager by choosing "Extensions" from the browser 'Tools' menu, select the MDHashTool listing, and click the uninstall button at the bottom of the window. Restart the browser to complete the removal.


Revised: 08/23/05

This document created and maintained with Mozilla Composercomposer taskbar gif