xSum Hash Utility

---

• About
  • Supported Algorithms
  • What Is A Hash Digest
• Arguments
  • Main Arguments
  • Sub Arguments
  • Other Arguments
• Syntax
  • --generate
  • --verify
  • --sign
  • --target
  • --digest
  • --algorithm
  • --output
  • --overwrite
  • --progress
  • --lowercase
  • --clipboard
  • --exclude
  • --key
  • --clearsign
  • --detachsign
• Features
  • Help Menu
  • Target Types
  • Automatic Checking
  • Benchmark
    • Standard Benchmark
    • Algorithm Stress Test Benchmark

---

Note

This utility is currently in development. Not all features are complete. If you see some aspect of the code that could be improved, you're more than welcome to commit. All code will be reviewed before it is accepted.

---

About

This utility allows you to generate, sign, and validate checksums.

While there are numerous apps available for doing things such as this; I need a tool that was very specific, and allowed for this to all be done very easily without complicated excessive options.

Supported Algorithms

Currently, the following algorithms are suppported. More are planned for later.

Algorithm	Family	Notes
CRC	8, 16, 32
MD5	MD5
SHA-1	SHA-1
SHA-2	256, 384, 512
SHA-3	128, 224, 256, 384, 512
Blake2b	128, 160, 256, 384, 512
Blake2s	128, 160, 256, 384, 512
Argon2	argon2i, argon2d	Strings Only

For a list of supported algorithms, type

xsum

Supports specifying algorithms with and without hyphens:

xsum --generate "MyFolder" --algo sha3-256
xsum --generate "MyFolder" --algo sha3256

What Is A Hash Digest

When using --generate, a hash digest will be created which contains a list of all the files you have targeted. When that digest is generated, it will be created as a file named depending on what hash algorithm you specified.

You may either specify your own name for the hash digest, or let the utility pick a name.

If you generated a hash digest using SHA512 and did not specify --digest <FILE>, your hash digest will be generated as SHA512.txt.

When you open the hash digest in a text editor, you will see something similar to the following:

d63ba16a664619c2dc4eb2aeef2a2e64cbc7931b831e0adf1c2275ee08e8fd47  example_file_1.txt
dfb8dacbd53eac730814ef2e9f74a47efabe5cb2a5e458bcad6380ae4c1f1f59  example_file_2.txt
9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08  sample_zip_1.zip
60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752  README.md

---

Arguments

The following is a description of all the arguments associated with this utility.

Main Arguments

The following arguments are considered the primary arguments of this utility.

Argument	Description
	Generate a new hash digest from the --target <FILE>
	Verify existing digest and compare folder with --target <FILE>
	Signs an existing hash digest using GPG

Sub Arguments

Along with the main features listed above, the following sub-arguments can be used to configure out xsum works for you:

Argument	Description
	Display help information
	Target folder or file to generate / verify hash for
	Hash digest which contains list of generated hashes
	Algorithm used to generate or verify hash
	Output log file for tasks
	Overwrite results to --output instead of append
	Displays progress info for each task step
	Match and output hash value(s) in lower case instead of upper case
	Copies the output hash value to clipboard.
	Clear console before each command executes
	Exclude files not hashed with -g and -v
	GPG key to use signing digests with --sign
	Sign the hash digest using GPG with a clear signature
	Sign the hash digest using GPG with a detached signature
	Perform benchmarks on a specific algorithm or all.
	Number of iterations to perform for --benchmark
	Buffer size to use for --benchmark
	Debugging information

Other Arguments

The following are a list of extra functionality:

Argument	Description
	Print list of out-of-box excluded files
	Prints all of the GPG keys in your keyring

---

Syntax

This utility attempts to be semi "smart" in the aspect that you can execute commands in various different ways. The reason for this is because out of the other hashing tools out there, we try to use a similar syntax for this utilities' commands so that there's very little in means of transitioning, and to make it more comfortable.

--generate

Compute hash for folder, files, or strings and generate new hash digest

_{Read More}

The --generate argument allows you to create a new hash digest from the target folder. This argument requires you to specify a target file or folder using one of the following ways:

Expects	Description
--generate Path\To\Folder	Folder to generate hash digest for
--generate --target Path\To\Folder	Same as above
--generate Path\To\File.xxx	File to generate hash digest for
--generate --target Path\To\File.xxx	Same as above

The following commands all do the same action:

xsum --generate --target "X:\Path\To\ExampleFile.zip" --algo sha256 --digest SHA256.sig
xsum --generate "X:\Path\To\ExampleFile.zip" --algo sha256 --digest SHA256.sig

xsum --verify --target "X:\Path\To\ExampleFile.zip" --algo sha256 --digest SHA256.sig
xsum --verify "X:\Path\To\ExampleFile.zip" --algo sha256 --digest SHA256.sig

---

--verify

The --verify argument allows you to verify an existing hash digest with the source files as they are on your system.

_{Read More}

To verify a hash digest, you need:

• Files for the project with the hash digest
• Hash digest

A hash digest is usually one of the following files:

• CRC*.txt
• MD5.txt
• SHA*.txt
• SHA3*.txt
• BLAKE*.txt

Inside the hash digest is a list of every file associated with the project, as well as the hash for that file, such as the following:

d63ba16a664619c2dc4eb2aeef2a2e64cbc7931b831e0adf1c2275ee08e8fd47  Project Folder 1/myfile.txt
dfb8dacbd53eac730814ef2e9f74a47efabe5cb2a5e458bcad6380ae4c1f1f59  Project Folder 2/example_file_2.txt
9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08  Project File 1.xxx
5FD924625F6AB16A19CC9807C7C506AE1813490E4BA675F843D5A10E0BAACDB8  Project File 2.xxx

To verify a hash digest against the actual files, execute the following:

xsum --verify --target "Project Folder Name" --digest SHA256.txt

If you have xsum.exe in the root project folder where the project files and hash digest exist, then you can execute:

xsum --verify --digest SHA256.txt

If you do not specify --target, xSum will automatically use the directory you are executing xsum.exe from.

📁 Project Folder 1
📁 Project Folder 2
📄 Project File 1.xxx
📄 Project File 2.xxx
📄 SHA256.txt
🗔 xsum.exe

The aboe file structure will allow you to verify all project folders and files.

Then a project is successfully verified, you will receive the following:

> xsum --verify --digest SHA256.txt

 Lowercase:     Disabled
 Clipboard:     Disabled

 Using "sha256" to verify hash of Folder "H:\xSum"
 Successfully verified Folder H:\xSum in digest SHA256.txt

If you are not using SHA256, then you will need to specify the hash algorithm:

xsum --verify --digest MD5.txt --algo md5

Remember: xSum verifies a hash digest using UPPER CASE characters. If your hash digest contains hashes in lower case, you must use:

xsum --verify --digest SHA256.txt --lowercase

---

--sign

The --sign argument allows you to sign a hash digest using a specified GPG key.

_{Read More}

This feature requires that you have GPG installed on your device, and added to your Windows Environment Variables. You can also install Gpg4Win.

To sign a hash digest with your GPG key, open command prompt and use --generate to generate your hash digest.

If you navigate to the folder where the project files are, you do not need to specify a --target. It will automatically use the current directory as the target path.

xsum --generate --algo SHA256 --lowercase

The command above will generate a new file named SHA256.txt and all hashes will be lowercase. After the new file is created, you can now sign it with GPG by running:

xsum --sign --key ABCD1234 --clearsign

The above command will sign SHA256.txt using the GPG key ABCD1234 with a Clear Signature. A new file will then be created which is named SHA256.txt.asc.

If you do not specify a signature type ( --clearsign or --detachsign ), then it will default to generating a Clear signature.

If you wish to sign with a detached signature, execute:

xsum --sign --key ABCD1234 --detachsign

To specify a target location to sign, execute:

xsum --sign --target "X:\Path\To\Folder\" --key ABCD1234 --detachsign

---

--target

Target folder or file to generate / verify hash for

_{Read More}

The Target is the file or folder you wish to either generate a hash for, or verify an existing hash.

This can be defined either by specifying the file or folder directly after using --target, or directly after the main command.

Expects	Description
--target Path\To\FILE.xxx	File to create / verify a digest for
--target Path\To\FOLDER	Folder to create / verify a digest for. All files in folder will be added to digest.
--target STRING	Creates an SHA hash for a string and prints to console.

The following commands all do the same action:

xsum --verify --target "X:\Path\To\ExampleFile.zip" --algo sha256 --digest SHA256.sig
xsum --generate --target "X:\Path\To\ExampleFile.zip" --algo sha256 --digest SHA256.sig

xsum --verify "X:\Path\To\ExampleFile.zip" --algo sha256 --digest SHA256.sig
xsum --generate "X:\Path\To\ExampleFile.zip" --algo sha256 --digest SHA256.sig

---

--digest

Hash digest which contains list of generated hashes

_{Read More}

The --digest <FILE> argument tells xsum either where your current digest is if you're using -verify, or where you want a new digest to be created if you are using --generate.

Expects	Description
--digest Path\To\FILE.xxx	The file to use as the hash digest for verifying

If you use --generate and do not define a hash digest, one will be generated and placed in the folder where the hashes were made, using the structure [AlgorithmName].txt

If you execute:

xsum --generate "X:\Path\To\ExampleFile.zip" --algo SHA512

The hash digest will be saved as SHA512.txt.

---

--algorithm

Algorithm used to verify --digest

_{Read More}

The --algorithm <HASH> argument specifies which algorithm to use for generation or verification.

Available Algorithms:

Algorithm	Command
--algorithm md5	MD5
--algorithm sha1	SHA-1
--algorithm sha256	SHA-256
--algorithm sha384	SHA-384
--algorithm sha512	SHA-512

---

--output

Output file which displays detailed information about each task.

_{Read More}

The --output argument is an optional parameter which allows you to define a file where the results of your generated or verified results will be placed.

The information provided by --output is different than the output to the hash digest using --digest.

The hash digest contains a list of each target file and its corresponding hash. However, the output file will display step-by-step of what is going on when the hashes are generated.

Expects	Description
--output Path\To\Output.txt	The file to output results to

---

--overwrite

Overwrite results to --output instead of append

_{Read More}

When used in combination with --output, this argument will force the utility to overwrite any existing output files. If you do not specify --overwrite, then your current task's results will be appended to any existing result files that may have been generated from previous tasks.

---

--progress

Displays in-depth information about the utility's progress during a task, as well as the checksum for each file being processed.

_{Read More}

The --progress argument allows you to see a more detailed report about what xSum is doing.

Without this argument, you will see a simple message stating whether or not your hash digest was successfully verified, or that your new digest has been created.

However, when using this argument, you will see a larger collection of messages.

_{--progress enabled}

_{--progress disabled}

---

--lowercase

Match and output hash value(s) in lower case instead of upper case.

_{Read More}

During normal operation when this utility is processing files, the hash that this utility generates is in upper-case characters. If your hash matches the one in the digest but has different casing, then the verification will fail. The casing of your digest hash, and the hash that the utility generates must be the exact same.

Without the argument --lowercase, the following verification will fail:

d63ba16a664619c2dc4eb2aeef2a2e64cbc7931b831e0adf1c2275ee08e8fd47  filename.zip

D63BA16A664619C2DC4EB2AEEF2A2E64CBC7931B831E0ADF1C2275EE08E8FD47

This argument will transform all hashes to lowercase, both the hash produced by the utility, and the hashes in your digest, which will allow them to match as long as the hash characters are the same.

---

--clipboard

Copies the output hash value to clipboard.

_{Read More}

When the argument --clipboard is specified, the results of a task will be copied to your clipboard.

[!NOTE] When targeting a folder to generate a hash, the hash of the folder itself will be copied to your clipboard, not the individual files.

---

--exclude

The --exclude argument gives you the ability to filter out files that should not be included when your dash digest is created.

_{Read More}

It allows for wildcard patterns so that you can match multiple files with one rule.

d63ba16a664619c2dc4eb2aeef2a2e64cbc7931b831e0adf1c2275ee08e8fd47  example_file_1.txt
dfb8dacbd53eac730814ef2e9f74a47efabe5cb2a5e458bcad6380ae4c1f1f59  example_file_2.txt
9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08  sample_zip_1.zip
60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752  README.md

As an example, you could exclude the files example_file_1.txt and example_file_2.txt from being hashed by utilizing the * wildcard:

--exclude *.txt

For multiple exclusions, append additional --exclude to the end of your command:

--exclude *.txt --exclude *D*

With the above rules in place, any file ending with .txt will be excluded, and the rule *D* will exclude the file README.md since it has a D in the name.

9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08  sample_zip_1.zip

---

--key

This argument defines which GPG key to use signing digests with --sign.

_{Read More}

xSum gives the ability to sign your hash digest using a GPG Key. This command does require that you have GPG installed on your system and added to your Windows Environment Variables.

xsum --sign --target SHA256.txt --key ABCD1234

The above command will use GPG key ABCD1234 to sigh the hash digest file in the current directory with a Detached Signature. In return, you will see a new file:

• SHA256.txt.asc

You can specify either --detachsign or --clearsign. If you want to sign your hash digest with a detached signature, execute:

xsum --sign --target SHA256.txt --key ABCD1234 --detachsign

In return, you will see a new file:

• SHA256.txt.sig

---

--clearsign

The --clearsign argument creates a clearsign signature using GPG.

_{Read More}

A clearsign signature wraps both the data and the signature into an ASCII-armored signature.

A digital signature certifies and timestamps a document. If the document is subsequently modified in any way, a verification of the signature will fail. A digital signature can serve the same purpose as a hand-written signature with the additional benefit of being tamper-resistant. The GnuPG source distribution, for example, is signed so that users can verify that the source code has not been modified since it was packaged.

When trying to clearsign a document using the GPG command-line, you could execute the following:

gpg -default-key <XXXXXXXX> --armor --clearsign <FILE>

xSum does this automatically without the need of using GPG. But you must have GPG installed on your system.

---

--detachsign

The --detachsign argument creates a detached signature file using GPG.

_{Read More}

This creates a separate signature file that is used to verify the original message if desired. In its simplest form, this file contains a hash of the original file data and is encrypted with the private key. Anyone with the public key can open the detached signature and then compare hashes to verify the integrity of the signed file.

When trying to create a detached signature for a document using the GPG command-line, you could execute the following:

gpg --default-key <XXXXXXXX> --armor --detach-sign <FILE>

xSum does this automatically without the need of using GPG. But you must have GPG installed on your system.

---

Features

The following features are highlighted to explain them in better detail:

Help Menu

We've attempted to give the user as much info as possible to make using the program easier. You can access the main help / commands menu by typing:

xsum
xsum /?
xsum ?

If you need help on a specific command, type the argument like you normally would, but append a question mark ? at the end, such as:

xsum --benchmark ?

_{Help menu for the command `benchmark`)}

---

Target Types

This utility handles various different types of input:

• Files
• Folder
• Strings

If your specified input is not detected as a valid file or folder, the utility will switch over to String Mode, which means that it will take the string you have provided, and return a hash for that string.

_{Standard string hashing (sha256)}

_{Standard string hashing (sha1)}

---

Automatic Checking

xSum will be typically launched using Command Prompt or Powershell and executing all xSum commands through one of those methods.

However, xSum has the ability to be launched as a regular executable. When you click on the xsum.exe executable, the utility will automatically go into Verify Mode. In order to utilize this mode, xsum.exe must be in the same folder as a hash digest file, which can be any of the following:

• CRC.*.asc
• MD5.*.asc
• SHA1.*.asc
• SHA256.*.asc
• SHA384.*.asc
• SHA512.*.asc
• BLAKE.*.asc

Once xSum finds the hash digest file, all of the files will be automatically checked.

If you attempt to run xsum.exe in a folder where a hash digest is not present, you will see the following screen:

---

Benchmark

xSum includes a Benchmark feature, which allows you to test the performance of the various different hashes.

The benchmark functionality includes a few different modes:

Mode	Description	Example Command
Standard Benchmark	Run each algorithm through a series of performance tests	xsum.exe --benchmark --buffer 32000000 --iterations 50
Algo Stress Test	Stress the processing speeds of one particular algorithm.	xsum --benchmark --algo md5 --iterations 100000

---

Standard Benchmark

This will test each algorithm by throwing a series of hashing tasks at it. The test will perform 2 Rounds for each algorithm in order to ensure everything is properly warmed up.

Each algorithm will be assessed using 4 methods:

Name	Method	Notes
Unmanaged	SHA*Cng
Managed	SHA*Managed	Not available for MD5
Crypto Service Provider (CSP)	SHA*CryptoServiceProvider
Create	SHA*.Create

This benchmark accepts two arguments:

Argument	Default	Min Value	Max Value	Description
--buffer	32000000	5242880 (5MB)	512000000 (512MB)	Size of bytes to use in test
--iterations	50	1	500000	Number of iterations for iteration test

xsum.exe --benchmark --buffer 32000000 --iterations 50

Algorithm Stress Test Benchmark

This test focuses on one specified algorithm when performing a series of tasks. The test will generate a large group of text and then hash that text in groups; progressively sampling larger sizes.

This benchmark accepts two arguments:

Argument	Default	Min Value	Max Value	Description
--algo	sha1	-	-	The algorithm to perform the test for.
--iterations	100000	1	500000	Number of characters to use in sample.

xsum.exe --benchmark --algo sha256 --iterations 100000