Getting Started
| Algorithm | Family |
|---|---|
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 |
This utility is for application developers who push releases of their own software to users. Once your application is ready to release, place the xsum.exe program in the parent folder of the files.
Generate a brand new hash digest for your project with a command such as the following:
xsum.exe --generate --algo sha256If you want to specify a target project folder not in the location of the xsum.exe file, add the path to the folder with:
xsum.exe --generate --target "X:\Path\To\Project" --algo sha256After executing the command, you will see a new file generated in your project folder called SHA256.txt (or whatever hash algorithm you selected).
Next, ensure you have a GPG key generated and installed on your system. You must download and install GPG4Win from the location below:
After one of the above are installed, add it to your Windows Environment Variables which can be accessed from your Windows start menu.
You will see two groups of boxes, User Variables and System Variables. Within the System Variables box, find PATH and click Edit.
Add a new environment variable which points to the path of where Gpg4Win is installed, you need to specify the folder where gpg.exe exists, which by default is:
C:\Program Files (x86)\GnuPG\bin\
If you are unsure of where gpg.exe is, launch the Windows File Explorer and search for it inside the folders:
C:\Program FilesC:\Program Files (x86)
Once you add the new path for GPG, close out any Command Prompt / Terminal windows you may have open The environment variables will only take affect in a new window.
You can test if it's working by opening Command Prompt or Terminal, and typing:
gpg --versionYou should see GPG return your current running version:
At this point, ensure you have generated a GPG keypair, there are tutorials online for doing this. Make sure they are added to GPG on your system. You can see your keys by executing:
gpg --list-keys
Next, go to your project folder where you generated your hash digest (*.txt) in the previous Generate step above. Then execute the following command to create a Clearsigned GPG Signature:
xsum --sign --target SHA256.txt --key F42F10AB
After executing, two new files will be generated.
The first file is a GPG clear-signed file with the name SHA256.txt.asc which will contain the following contents:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256
9921C3AE6574481589DCFA1B0CEC01347B99D553D70A231A0055F05831E3024C my_program.exe
AC15D6436641A0358CB1F4B7C4FEC078B2897E6963F6198F12365B1D7B25ADAB README.txt
-----BEGIN PGP SIGNATURE-----
iQIzBAEBCAAdFiEE5d8yvBuKlFyrmbA1aV6J6vQvEKsFAmXB9O4ACgkQaV6J6vQv
EKuuDQ/8DZfh4RRt0R9fXUpt4RyjnzUevi9Idw7wDavMQrWmlbsqbPSZj241iQ+1
7ZSB7lP6m7ANY/vC1E/w2k4wTyTdcudGRBKmbLTzrkXvWcBuoOgu93jgzkovbfT2
9DmW8T3j1FSkdvzSZdjARbByB838XQBLRTVDgs7qdRMdLfvw5if6XST8AHoYDsHX
tU61O+nDDIlBLP/j5YQB0gvRyGPtuVeFMEgFwXTBjIiGwAWoNwFvIU935b77LwjP
B0G6NBpBqfQSSGsAdJqH73LZx1UP4UxkGfryoJ5TFi7P8UpqYd8YmthPLw7wbMto
/LM3tJXPQPJtkt2bEXe/0bJnwnvT+veL5AnPGp5MqZRutDIoUJ33/cPW9WTub7oM
D2OfH5ASoLraSB6DNsdNT4aJlzvUEVi9WamlY3oYKjgzuCI4JktwP9lpbScILPdH
OejQwqecnQAKHBPvf5g9oZeZNCpl6NbElgk/7X8gyE645HC3BAqrwAA+dNL2J5Dr
EDfaBpZALUbBFIQ0NRJqrjttPU4JpL9uNFpVPfGNXmXJB4MPRCk13NXMp6OMwlMc
sQpkDrpdqA26HivJYu/swJlbQLFnI/YG46Fl107h5S4acVn4WrW+qayg2QT5y8mz
qT5vb8ZdIkvg7JzVSZm0B3sdBvOt500xWQwX3QIitC7vSCeoMEQ=
=1im4
-----END PGP SIGNATURE-----
The second generated file will be a GPG Detached Signature file with the name SHA256.txt.sig with the following contents:
-----BEGIN PGP SIGNATURE-----
iQIzBAABCAAdFiEE5d8yvBuKlFyrmbA1aV6J6vQvEKsFAmXB9c4ACgkQaV6J6vQv
EKsjBg/8Ds18/Kok1l/HPLCkE6X1jdnjtHBAVQAztLgTlLUi8jNrfIkQxzEtgSgk
2MjxHg++GuYMT5JsVOnFaUVN+Qv/N4UP9Yac5UjTdk8t0BWefj4znKsdBSXsnYQ+
vIzgvzSSYixrxTER/PT4OScFE2bXaWatplMUwT9yhsQEAqMbT7pvyCyOOMioNkRJ
jnjKqzFlJWSbM1PM/3sX8Hd151oVorjAbVy/n1YMNaEJ/AbfoiWm6jzIrBgefaU+
6tvmrpFc82/2DHnO3pCj+B4lnZa8CsdLE5bGZN4NZrQoEAOe2w4ZeSxfC446My73
lIaWTb663/9tLnacpjCLd5PpUlIuUsRwo9oMaluT80KP6nbb9QhXPSbbwiwA3S+9
LwZMHc5pRkcFw0+zUMvRgXtilW8WGuzGW8j1O7P2/kOdRiKAJ6qhVxUlGRdJN6y8
XWMbBaJmIl/AI8iX1+VK6SeWQ24hZQAcVY7UTgwj9l2cWEplLiku/8jsiJXDisTJ
d6V3ZHKJju9wBl5zufnYSyrHwtMeNI60qHSXhv+TxKROAIAZcrbxfGkWM2xlc5/B
dKpQ4OR1DFc2b13XVJr+6Ool8X5uvkM3AvFgnwWE9QzQBsIOB8Ru2I0slK32sQZN
wvD5QadKQAyqFPEegi8bnd048MUgDKr4eZG+7rW/7okeJlSRA2c=
=I4rT
-----END PGP SIGNATURE-----The two generated signature files have the following roles:
| File | Type | Usage |
|---|---|---|
*.txt.asc |
Clearsigned Signature | File contains a list of every file in your project folder, along with the associated hash for each file, which is signed with your GPG key |
*.txt.sig |
Detached Signature | File verifies the authenticity of the clear-signed *.txt.asc file |
Review the section Verify for instructions on how the above files are verified by users.
After you've generated a hash digest and signed your files, you can now release your project.
Along with all of the files for your project, you need to copy the two new generated files *.txt.asc and *.txt.sig and place them in the top-most root directory of your project. Typically they go in the same folder as your README.
When users download the latest version of your project, they should see your project files, and also your two newly generated files:
-
SHA256.txt.asc- Clearsigned hash digest with the list of files and hashes for your project
-
SHA256.txt.sig- Detached signature file
You can either include xSum.exe in your release, or provide instructions in your README on how to download xSum.exe. The user will use xSum in order to verify your release.
If you decide to include xSum.exe with your project, place it in the same location as the *.txt.asc and *.txt.sig files, which is in the top / root directory of your project.
Placing xSum.exe in your project's top directory of your project ensures that the user does not have to execute any commands.
When xSum.exe is placed in the parent folder of your released project, all the user has to do is double-click the xsum.exe program, and it will launch Self-Verification.
The self-verification system will try to automatically find the included *.txt.asc file in the folder and read it. The app will then scan every file in the project folder, and compare the hashes with what is included in the .*.txt.asc file. If all of the files have exactly the same hashes, it will return a success message.
If the hashes do not match, it will warn the user and list the files that failed.
Next, self-verification will open the .txt.sig detached signature file. This file is used to confirm that your hash digest file .txt.asc is authentic and signed by the real developer.
It will throw a warning if the file is not authentic.
If the user does not double-click on the xsum.exe, they can also verify everything manually if they are an advanced user.
To verify the hashes of all the project files against the signed hash digest file *.txt.asc, run the following command:
xsum --verify --digest SHA256.txt.asc
The xSum --verify command above will confirm two things:
- Checks the project's file hashes against the hash digest generated (
*.txt.asc) - Verifies the hash digest
*.txt.ascis signed with a valid GPG key and compares it to the deteched signature file*.txt.sig. It then returns the status.
If you'd like to manually verify the GPG key using gpg.exe, you can execute:
gpg --verify SHA256.txt.sig SHA256.txt.ascThis however, is not required unless you wish to just verify it using GPG instead of xSum. The above command should output something similar to below, however, it will contain your own GPG key information:
gpg: Signature made 2/6/2024 01:00:00 AM Timezone
gpg: using RSA key E5DF32BC1B8A945CAB99B035695E89EAF42F10AB
gpg: Good signature from "Aetherx <aetherx@me>" [ultimate]