File Hashing

API

Tip: For detailed documentation refer to the IntelliSense tips that appear when you call a given API method.

(Note: The high-level file transfer API supports automatic hashing after upload/download).

• CompareFile() - High level method that compares a local file against a remote file on the FTP server using various kinds of quick equality checks. Configurable to compare any combination of: file size, checksum, date modified. Comparing the checksum of a file is a quick way to check if the contents of the files are exactly equal without downloading the file.

• GetChecksum() - Retrieves a checksum of the given file using a checksumming method that the server supports, if any. The algorithm used goes in this order : HASH, MD5, XMD5, MMD5, XSHA1, XSHA256, XSHA512, XCRC.

• HashAlgorithms - Get the hash types supported by the server, if any (represented by flags).

Examples

C#

• GetChecksum.cs

VB.NET

• GetChecksum.vb

How do I verify if a file has uploaded/downloaded correctly?

Use the CompareFile method to compare a local file against a file on the FTP server. It will tell you if they are exactly the same or if they are different in any way. It supports the following options:

• FtpCompareOption.Auto - Compares the file size and checksum of the file.

• FtpCompareOption.Size - Compares the file size.

• FtpCompareOption.DateModified - Compares the last modified date of both files using UTC timestamp.

• FtpCompareOption.Checksum - Compares the checksum/hash of the file using any algorithm supported by the server, such as CRC32, MD5 or SHA.

• You can combine the Size, DateModified and Checksum flags using the | operator.

Alternatively, you can automatically perform post-download or post-upload verification by passing the FtpVerify flag to any download/upload method. More on that here.

How do I verify the checksum of a file and automatically retry uploading/downloading?

All the major file transfer methods support automatic checksum verification. After the transfer has completed, the files are checksummed/hashed and the hashes are compared. If there is a mismatch in hashes, the file is re-transferred, or an exception is thrown, depending on configuration.

The following methods support automatic checksum verification:

• UploadFile
• DownloadFile
• UploadFiles
• DownloadFiles
• UploadDirectory
• DownloadDirectory
• TransferFile
• TransferDirectory

For example:

// retry 3 times when uploading a file
client.RetryAttempts = 3;

// upload a file and retry 3 times before giving up
client.UploadFile(@"C:\MyVideo.mp4", "/htdocs/MyVideo.mp4", FtpExists.Overwrite, false, FtpVerify.Retry);

All the possible configurations are:

• FtpVerify.OnlyChecksum - Verify checksum, return true/false based on success.

• FtpVerify.Delete - Verify checksum, delete target file if mismatch.

• FtpVerify.Retry - Verify checksum, retry copying X times and then give up.

• FtpVerify.Retry | FtpVerify.Throw - Verify checksum, retry copying X times, then throw an error if still mismatching.

• FtpVerify.Retry | FtpVerify.Delete - Verify checksum, retry copying X times, then delete target file if still mismatching.

• FtpVerify.Retry | FtpVerify.Delete | FtpVerify.Throw - Verify checksum, retry copying X times, delete target file if still mismatching, then throw an error

Which hashing algorithms are supported?

• We support the MD5 command as described here.

• We support the MMD5 command as described here.

• We support the HASH command for retrieving SHA-1, SHA-256, SHA-512, and MD5 hashes from servers that support this feature as described here.

• We also support XCRC, XMD5, XSHA1, XSHA256, XSHA512 which are non-standard commands.

• If you are calling the low-level methods like GetMD5 or GetXCRC, then you must check the FtpClient.Capabilities flags for the respective flag (XCRC, XMD5, XSHA1, XSHA256, XSHA512) before calling these methods.

• When you call the high-level method GetChecksum, the FtpHash object returned has the method ftpHash.Verify() to check the result against a given stream or local file.