The majority of software distribution occurs electronically. However, the larger the downloads, the larger the risk of corrupted data transfer. Hence, it's very useful to be able to verify the integrity of downloaded files. Cryptographic hashing algorithms provide one way to do this. A hashing algorithm takes a series of bytes (such as the bytes of a file), performs a calculation using those bytes, and produces an output value of a fixed size (e.g., 128 bits, 160 bits). The goal of these hashing algorithms is that no two inputs should produce the same output. Two common hashing algorithms are the Message Digest 5 Algorithm (MD5) and Secure Hash Algorithm-1 (SHA1). These algorithms have been shown to contain flaws (i.e., there’s the possibility that two different inputs can produce the same output), but they’re robust enough to verify file integrity in the vast majority of cases.
Figure 1: An SHA1 hash value for an .iso file
Figure 1 and Figure 2 show practical examples of hash values. Figure 1 shows an SHA1 hash value for an .iso file on Microsoft TechNet. Figure 2 shows two MD5 hash values for OpenOffice.org installers. If you download these files, you can calculate the SHA1 or MD5 hash values to verify whether the files downloaded without any data corruption.
Figure 2: MD5 hash values for OpenOffice.org installers
Introducing Get-FileHash.ps1
Microsoft doesn't provide a command to calculate hash values for files, so I decided to write a Windows PowerShell script, Get-FileHash.ps1, that calculates MD5 or SHA1 hash values for files using the Microsoft .NET Framework. The script requires PowerShell 2.0 or later. You can download it by going to www.windowsitpro.com, entering 139518 in the InstantDoc ID text box, and clicking the 139518.zip hotlink. I recommend placing the Get-FileHash.ps1 file in a directory in your path.
To execute the script, follow the syntax
Get-FileHash [-Path] <String[]>
[-HashType <String>]
or
Get-FileHash -LiteralPath <String[]>
[-HashType <String>]
The -Path parameter name is optional and specifies one or more files for which you want to output a hash value. Wildcards are permitted. The script will accept pipeline input in place of the -Path parameter.
If you want to specify the name of a file that contains characters that PowerShell normally interprets as escape characters (e.g., the square bracket characters [ and ]), you can use the -LiteralPath parameter and one or more filenames. If you use -LiteralPath, you can’t use wildcards and the script will ignore pipeline input. Note that the -Path and -LiteralPath parameters are mutually exclusive.
The -HashType parameter's value must be the string MD5 or SHA1. If you omit -HashType, MD5 is the default.
Get-FileHash.ps1 outputs objects containing each file's path and its MD5 or SHA1 hash value. Figure 3 shows a sample command and its output. In this command, the filenames are being provided through pipeline input.
Figure 3: Sample command and its output
Understanding the Script
Get-FileHash.ps1 uses two features new to PowerShell 2.0 and later: Comment-based help and advanced function parameters. Comment-based help enables the Get-Help cmdlet to display help information for the script. Advanced function parameters allow the script to behave like a cmdlet.
Comment-based help is a series of comment lines (lines beginning with #) or a comment block (text enclosed between <# and #>) that contains special keywords that PowerShell uses to generate help information. If you use the command
Get-Help Get-FileHash
PowerShell uses the special keywords (e.g., .SYNOPSIS, .DESCRIPTION, .PARAMETER) to generate the help text. Comment-based help is a great addition to PowerShell 2.0 that makes it very easy to self-comment functions and scripts. Run the command
Get-Help about_Comment_Based_Help
at a PowerShell prompt for more information about how to use comment-based help.
Advanced parameters cause PowerShell to use cmdlet-like rules for parsing the script's command-line parameters. Get-FileHash.ps1 uses parameter sets, which enable the script to accept mutually exclusive parameters.
Listing 1 shows the script's CmdletBinding attribute and param statement. CmdletBinding enables cmdlet-like behavior for the script's parameters and specifies the default parameter set. The param statement contains three parameters, which are declared with Parameter statements. Each Parameter statement includes attributes that establish the parameter’s behavior. The attributes are as follows:
- ParameterSetName="Name": Specifies the parameter set to which the parameter belongs (either Path or LiteralPath). If a parameter doesn’t specify a parameter set, it’s valid for any parameter set. The ParameterSetName property of the $PSCmdlet object contains the current parameter set name.
- Position=n: The parameter's position on the command line. Position=0 means the parameter must appear first, Position=1 means the parameter must appear second, and so forth.
- Mandatory=$TRUE: Specifies that the parameter is required. If the parameter isn’t specified, PowerShell will prompt for input for the parameter.
- ValueFromPipeline=$TRUE: Specifies that the parameter's input can come from the pipeline.