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:

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

• 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 XCRC, XMD5, XSHA1, XSHA256, XSHA512 which are non-standard commands.

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

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