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.

• MD5
• SHA1
• SHA2-256
• SHA2-384
• SHA2-512
• SHA3-224
• SHA3-256
• SHA3-384
• SHA3-512
• Blake2b-128
• Blake2b-160
• Blake2b-256
• Blake2b-384
• Blake2b-512
• Blake2s-128
• Blake2s-160
• Blake2s-256
• Blake2s-384
• Blake2s-512

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

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.

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

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

xsum --verify --digest SHA256.txt

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

> 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

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

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

--sign

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

xsum --generate --algo SHA256 --lowercase

xsum --sign --key ABCD1234 --clearsign

xsum --sign --key ABCD1234 --detachsign

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

--target

Target folder or file to generate / verify hash for

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

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

--algorithm

Algorithm used to verify --digest

--output

Output file which displays detailed information about each task.

--overwrite

Overwrite results to --output instead of append

--progress

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

--lowercase

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

d63ba16a664619c2dc4eb2aeef2a2e64cbc7931b831e0adf1c2275ee08e8fd47  filename.zip

D63BA16A664619C2DC4EB2AEEF2A2E64CBC7931B831E0ADF1C2275EE08E8FD47

--clipboard

Copies the output hash value to clipboard.

--exclude

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

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

--exclude *.txt

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

9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08  sample_zip_1.zip

--key

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

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

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

--clearsign

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

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

--detachsign

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

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

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:

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

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:

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