File Hashing

API

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

High level API

• 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).

Low level API

• GetHash() - Gets the hash of an object on the server using the currently selected hash algorithm. Supported algorithms are available in the HashAlgorithms property. You should confirm that it's not equal to FtpHashAlgorithm.NONE (which means the server does not support the HASH command).

• GetHashAlgorithm() - Query the server for the currently selected hash algorithm for the HASH command.

• SetHashAlgorithm() - Selects a hash algorithm for the HASH command, and stores this selection on the server.

• GetMD5() - Retrieves the MD5 checksum of the given file, if the server supports it.

• GetXMD5() - Retrieves the MD5 checksum of the given file, if the server supports it.

• GetXSHA1() - Retrieves the SHA1 checksum of the given file, if the server supports it.

• GetXSHA256() - Retrieves the SHA256 checksum of the given file, if the server supports it.

• GetXSHA512() - Retrieves the SHA512 checksum of the given file, if the server supports it.

• GetXCRC() - Retrieves the CRC32 checksum of the given file, if the server supports it.

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 that can be combined in any way:

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

• FtpCompareOption.Size - Compares the file size.

• FtpCompareOption.DateModified - Compares the file size.

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

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.

What kind of hashing commands are supported?

• We support XCRC, XMD5, XSHA1, XSHA256, XSHA512 which are non-standard commands. You must check the FtpClient.Capabilities flags for the respective flag (XCRC, XMD5, XSHA1, XSHA256, XSHA512) before calling these methods.

• We support the MD5 command as described here has also been added. Again, check for FtpFeature.MD5 before executing the command.

• We support the MMD5 command as described here has also been added. Again, check for FtpFeature.MMD5 before executing the command.

• We support the HASH command for retrieving SHA-1, SHA-256, SHA-512, and MD5 hashes from servers that support this feature. The returned object, FtpHash, has the method ftpHash.Verify() to check the result against a given stream or local file. You can read more about HASH in this draft.

How do I verify the hash/checksum of a file and retry if the checksum mismatches?

Add the FtpVerify options to UploadFile() or DownloadFile() to enable automatic checksum verification.

// 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