FAQs


Installation questions

Why should I use Jacksum rather than ...?

Your data is one of the most important things you own. Jacksum helps you to keep control of the integrity of your data and. Jacksum is very stable and reliable and it provides a lot of unique features. If you are clever, you are going to compare the features of those tools with Jacksum's feature list above and you will be able to answer the question above by your own  ;-)

 
How much is it?

Jacksum ist free of charge.

 
Where can I download this software ?

here
 

What platforms are supported ?

Microsoft Windows, GNU/Linux, Mac OS X, Solaris and others. See also requirements, features and screenshots.

 
How to install this software ?

Please read the install instructions.

What Java version should I use?

Jacksum 1.7 runs on JRE 1.3.1 and any later release. However, it is recommended to use at least JRE 8, because all public Java releases prior to version 8 are not supported anymore by Oracle.


[Ubuntu] I would like to use the Java Runtime Environment from Oracle. How can I do that on Ubuntu ?

Download the JRE from java.com and install it, for example to

/java/jre/64/latest8/

Run update-alternatives. See also https://help.ubuntu.com/community/Java

$ sudo update-alternatives --install "/usr/bin/java" "java" "/java/jre/64/latest8/bin/java" 1
$ sudo update-alternatives --config java

If you want to be flexible as possible, you could create /java/jre/64/latest8 just as a symbolic link to the actual Java folder. The advantage would be that each time a new JRE comes out you just have to update the symlink.



Usage questions



Is there a GUI for Jacksum?

In addition to the standard command line interface, the Jacksum project also supports the integration into the famous file browsers such as Windows Explorer, KDE Konqueror, Gnome Nautilus, ROX-Filer and Finder on macOS.

Jacksum's primary user interface is and will be the command line, as it provides compatibility with other popular command line tools available on Unix, like cksum, sha1sum, sum and md5sum. The commandline interface allows you also to use the tool also easily with cronjobs, in scripts, in file browsers, in web interfaces and of course in combination with pipes and other useful tools like grep, sort, uniq, tar, bzip2, gzip and zip.

Jacksum also supports a public API. It can be used by a Graphical User Interface (GUI) for example.


What's the meaning of the Jacksum output?

e. g..
599770357    23560    foo.txt

The first number represents the CRC, checksum or hash. It depends on the algorithm that you use (option -a) and whether you have specified the hex option (option -x, respectively option -X). The second number represents the filesize, usually in bytes. Exceptions are both algorithms BSD sum and UNIX system V sum,  they print the filesize in blocks. The filesize will be not written by any One-Way-Hash based algorithm (e. g. SHA1, MD5, etc.), because the filesize is already incorporated into the message digest. The third column (it is the second one if you have specified a one-way-hash based algorithm) represents the filename. The filename will not be written if the standard-input device is used.

Starting with Jacksum 1.3.0 you have the option to print the timestamp of files. In this case an additional column appears in each line (just before the filename). The meaning of the timestamp is dependent on the format that you can specify (option -t).

599770357    23560    20031027140042     foo.txt

Starting with Jacksum 1.5.0 you have the full control on the output by using the option -F.


It seems the Jacksum calculates wrong values if standard input is being used

Jacksum 1.7.0 and earlier versions operates in text mode if standard input is being used. The next major version, Jacksum 2.0.0, will operate in binary mode by default if standard input is being used. See also Feature Request #11: https://sourceforge.net/p/jacksum/feature-requests/11/ (Read binary rather than text from standard input).


Which algorithm should I use?

With option -a you can choose one of many algorithms. If you got a file from a trusted source and you only would like to know if a file transfer was successful, many algorithms can be used. However, for a really save file integrity check and verification on thousands of files on today's harddisks (see also option -c), not all algorithms are suitable in this case.

Don't use:
From a cryptographic point of view, it is recommended not to use the following algorithms, because they don't care about the arrangement of bytes in a file: sum8, sum16, sum24, sum32 and xor8. Furthermore you shouldn't use MD2 or MD4, because RSA doesn't recommend to use them anymore. SHA-0 is also weak, it was replaced by SHA-1 in year 1995.

Limited usability:
All checksum and CRC based algorithms like Adler32, BSD sum, POSIX cksum, CRC-8, CRC-16, CRC-24, CRC-32 (FCS-32), FCS-16, MPEG-2's CRC-32, CRC-64, the generic CRC and the Unix System V sum do not have the bit strength and the mathematical power to guarantee strong fingerprints for thousands of files on today's harddiscs. See also the CRC-Faker and read the article "CRC and how to Reverse it" (http://surf.to/anarchriz). Viruses could be able to fake files - with a CRC based algorithm you cannot detect such intruders. Although Jacksum is able to produce SFV on demand, it is highly recommended to avoid using SFV files. They are based on CRC32 values and SFV doesn't take the filesize into account. SFV is really history.

Not really recommended:
ELF-32 is a very simple hash based algorithm and has not the bit strength for save file integrity checks, probably. The Whirlpool has been replaced two times by a new Whirpool. The algorithm eMule/eDonkey (MD4 based, but improved) would have enough bits, but even for the widely used MD5 and HAVAL_3_128 real collisions have been detected already (http://eprint.iacr.org/2004/199/) in August 2004 (with a non-brute force method). The paper also mentions collisions for the full RIPEMD-128, however the hexdump example in the doc doesn't generate a collision (while all the other examples in the doc have been verified, the RIPEMD hexdump example seems to have a typo). For an excellent example of a MD5 collision go to http://www.cits.rub.de/MD5Collisions. Note that RIPEMD-256 is as secure as RIPEMD-128 so it is also not recommended. Tiger/128 and Tiger/160 are truncated hash functions of Tiger/192. Although they seem to be save today, the non-truncated has functions are more secure.

SHA-1
In February 2005, Bruce Schneier reported an attack by Xiaoyun Wang, Yiqun Lisa Yin, and Hongbo Yu. The attack is outlined in a brief note by the authors. The authors assert that their attacks can find collisions in the full version of SHA-1, requiring less than 269 operations (a brute-force search would require 280). In academic cryptography, any attack that has less computational complexity than the expected time needed for brute force is considered a break. This does not, however, necessarily mean that the attack can be practically exploited. So in the real world, the SHA-1 is still secure, at least for verifying integrity. For latest cryptanalysis of SHA-1 read http://en.wikipedia.org/wiki/SHA1#Cryptanalysis_of_SHA-1.

Recommended:
From a today's cryptographic point of view (Februar 2016), the following one-way-hash algorithms are save to perform file integrity checks: HAVAL-{3/4/5}-{160/192/224/256}, RIPEMD-160, RIPEMD-320, SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, Tiger, Tiger2 and the second revision of Whirlpool. Jacksum supports all those algorithms. Since Jacksum 1.5.0, the algorithm SHA-1 is the default.

Since Jacksum 1.7.0 you can combine multiple algorithms together. I recommend to combine at least two different techniques, a hash algorithm such as SHA-1 and a CRC such as CRC32 are a very good combination for file integrity checks. Even if a collision will be found in the future for a hash based algorithm, it is very unlikely that also a CRC returns equal values in this case.

Why are there alternate implementations available?

A few algorithms (adler32, crc32, md5, sha-1) are part of the standard Java API. A few others (sha-256, sha-384, sha-512) are part of a newer Java API. If  an algorithm is provided by your JRE, Jacksum is just calling the API and use the algorithm which is offered by the JRE. Some vendors of the JRE are calling native code which results usually in a good performance. But note, that this is the implementation detail of the vendor of a JRE and can be vary from vendor to vendor and from version to version. Due to several requests I also provide alternate, pure Java implementations for all of the algorithms which are usually covered by the Java API. On some systems an alternate implementation can perform much better (the MD5 for example), but this depends on the performance on your computer and on the Java Runtime Environment you use. Usually it is a good idea to use the latest JRE and rely on the performance the JRE can offer. Tests have shown that the newer your JRE, the better the performance. In some cases with the option -A you get better performance.

Are CRCs obsolete today ?

No, CRCs are still used in hardware, firmware, protocols, simple software installers (NSIS for example) and today's filesystems (ZFS on Solaris for example). Usually they are fast (and not so complex like one-way-hashes), and they are useful to verify a small amount of data. Furthermore, they are a very good addition to hash based algorithms. Jacksum supports the "Rocksoft (tm) Model CRC Algorithm" which makes it possible to calculate any customized CRC.

How is a CRC calculated ?

A lot of people were asking me this question. Well, there are some good websites explaining how CRC is working. Go to http://surf.to/anarchriz or ftp://ftp.rocksoft.com/papers/crc_v3.txt. You also might have a look at the sourcecode of Jacksum.


Does Jacksum support the CCITT checksum algorithm ?

Many references define the CRC-16/CCITT as

    crc:16,1021,FFFF,false,false,0

The notation "crc:width,poly,init,refIn,refOut,xorOut" is used since Jacksum 1.7.0 to specify a CRC algorithm according to the Rocksoft(TM) Model CRC Algorithm. Using the message 123456789, a CRC algorithm with the parameters above returns 0x29B1:

  jacksum -q txt:123456789 -a crc:16,1021,FFFF,false,false,0 -X
  29B1

However, other sources claim that according to the CCITT standard (see above), a message must be prepended with 16 zero bits before the calculation. This interpretation of the standard can be expressed as

    crc:16,1021,1D0F,false,false,0

Notice, that in this case only the init value is different, because using a 16 bit zero message, a CRC with the init parameter 0xFFFF returns 0x1D0F which is the init value for the alternate interpretation of the algorithm.

Using the message 123456789, a CRC algorithm with the parameters above returns 0xE5CC:

  jacksum -q txt:123456789 -a crc:16,1021,1D0F,false,false,0 -X
  E5CC

Well, it is entirely up to you to select the CCITT standard you believe ;)
Jacksum is able to calculate both algorithms (and even any other interpretation of this "standard").


What algorihms are currently not supported by Jacksum?

There are still a lot of algorithms not (yet) supported by Jacksum. Those are called Cellhash, Boognish, DHA-256, FEAL (patented), FFT-hash, FORK-256, Panama (broken), Snefru (broken), DSS1, MAA (Message Authenticator Algorithm, broken), MDC2 (Patent ended), Maelstrom-0, Maelstrom-1, Maelstrom, N-Hash (patented, insecure), PMD-N, PMD-V, PMD-128, PMD-160, PMD-192, PMD-224, PMD-256 (korean standards, no complete english docs are available), RadioGatún, VEST-4, VEST-8, VEST-16, VEST-32 (patent pending), VMS/VAX checksum (very little information available), VSH. If you own sourcecode to one of those algorithms (Java sourcecode is preferred of course), please just send them to me and I will test, optimize and include them for a next release of Jacksum. Notice, that most of those "not yet supported algorithms" are not really strong, have usage restrictions due to patents and for most of them collisions have been detected or they are already broken. Nevertheless they are on my wishlist for educational and completeness purposes.

 

How do I sync two folders on two different computers?

With Jacksum, you can perform an unidirectional synchronization, e. g. if you want to sync two folders on two different computers, even without a connection in between, Jacksum can help you to solve that kind of problem. Let's imagine that you have a good and a faulty computer.

Example for Windows:
1. Change to the good folder on the good computer and execute the command
  cd good
  jacksum -a sha1 -m -r . > c:\temp\check.jacksum

2. The file called check.jacksum represents a snapshot of all files on the good computer from the good folder.
    Transfer the file called check.jacksum file to the faulty computer.

3. Change to the folder on the faulty computer and execute the command
  cd faulty
  jacksum -c c:\temp\check.jacksum -l > c:\temp\files.list

4. The file called files.list now contains a file list of differences.
    Transfer the file called files.list to the good computer.

5. Change to the good folder on the good computer again and execute the command
  cd good
  type files.list | zip -@ patch.zip

    In case you prefer .tar.bz2 rather than .zip:
  cd good
  tar cfv patch.tar -I files.list
  bzip2 -9 patch.tar

6. The file called patch.zip respectively patch.tar.bz2 contains all files from the good computer which were modified or deleted on the faulty computer. Transfer the file called patch.zip respectively patch.tar.bz2 to the faulty computer and extract the files included in the zip to the faulty folder. The faulty folder on the faulty computer become a good folder and you fixed the problem on the faulty computer. 

 

How do I create a patch with Jacksum?

As being a developer you might provide a patch to your faithfully customers so they can upgrade easier. Jacksum can help you in this case.

Example for Unix/Linux:
1. Change to your new version's folder
  cd ~/newversion
  jacksum -a sha1 -f -m -r . > /tmp/check.jacksum

2. Change to your old version's folder
  cd ~/oldversion
  jacksum -c /tmp/check.jacksum -l > /tmp/files.list

3. Change to your new version's folder again and zip the original files
  cd ~/newversion
  tar cfv patch.tar -T /tmp/files.list   (GNU/Linux, Mac OS X, PC-BSD)
  tar cfv patch.tar -I /tmp/files.list   (PC-BSD, Solaris)
  bzip2 -9 patch.tar

    In case you prefer .zip rather than .tar.bz2:
  cd ~/newversion
  cat /tmp/files.list | zip -@ patch.zip (GNU/Linux, Mac OS X, Solaris)

Thanks to Girish Narang who collaborated with me on developing a patch creator solution with Ant. Download the Ant script and a corresponding property file to create patches with Jacksum and Ant.

 

Is it possible to compare two directory trees or even discs?

Yes, there are multiple ways to do that. I recommend the first way.

1. Since Jacksum 1.3.0 you can use the option -c to check files against a given list, so you will exactly know which file has been modified or deleted. You create such a list with option -m. See the following example (batch file for windows). Notice, that you can also compare two directories or even discs even if they are on two different computers without a connection in between! See also How do I sync two folders on two different computers?

Example for Windows:

@echo off
:: usage: dircmp dir1 dir2
:: dir2 may be also on a different drive
set ERRORLEVEL=
if not exist %1 goto error
if not exist %2 goto error
set BACKUP=%CD%
call jacksum -a sha1 -r -f -O %TEMP%\tmp.jacksum -U nul -m -w %2
cd %1
call jacksum -c %TEMP%\tmp.jacksum
rem echo %ERRORLEVEL%
cd %BACKUP%
goto end
:error
echo direcotry does not exist
:end

2. Execute the following commands on both directories (it is important to change the directory with cd first):

cd <the directory you want to check>
jacksum -r -f -a sha1 . | jacksum -a sha1 -

If both checksums are equal, you will know, that both directories (including subdirectories) are equal.

3. Since Jacksum 1.5.0 there is the option -S to get just one checksum back. You don't need the pipe mechanism anymore.

cd <the directory you want to check>
jacksum -a sha1 -f -S -r .

 

Why do I receive different checksums with -S on two identical folders?

It makes a difference if you calculate a checksum on c:\data or d:\data for example, because Jacksum takes those differences into account. If you don't want Jacksum to incorporate the (absolute) path information you have given at the commandline, you must change the current working directory first or use option -w. I recommend to specify relative paths like "data" (if the current directory is c:\) or "." (if the current directory is c:\data) rather than "c:\data".  If you perform the calculation on d: you must use the same parameters you have used on drive c:.  See also feature request #1028816.

wrong expectation - all checksums will be different:
jacksum -a sha1 -S c:\data
jacksum -a sha1 -S d:\data
jacksum -a sha1 -S d:\backup\data

correct usage - all checksums will be equal, assumed that files and folders are really identically:

jacksum -a sha1 -S -w c:\data
jacksum -a sha1 -S -w d:\data
jacksum -a sha1 -S -w d:\backup\data

OR

c:
cd \data
jacksum -a sha1 -S .

d:
cd \data
jacksum -a sha1 -S .

cd \backup\data
jacksum -a sha1 -S .

Why do I receive different checksums with -S on Windows and Linux?

I have a share partition. It is formatted as FAT32 so I can access files from both Linux and Windows. If I use the option -S, I get different checksums on a particular subtree on Linux and Windows. What's wrong?

Usually this happens if you have suboptimal mount options. If your share partition is mounted as "vfat" under Linux you should also specify the mount option called "shortname". It defines the behaviour for creation and display of filenames which fit into 8+3 characters. The mount option is necessary, because the Jacksum option -S incorporates also the filenames into the checksum. For more information see also "man mount". Alternatively use the Jacksum options -m and -c to verify files in a platform- (and mount option) independent way.

How can I use Jacksum for website content change detection?

Let's assume that you would like to get informed about any modifications on this web page (http://www.jonelo.de/java/jacksum).

1. Preparation: Get the web page with the command called wget, and store the web page to your hard disk by specifying a suitable name (rather than index.html) and calculate a hash from the file:
wget http://www.jonelo.de/java/jacksum/index.html -O MyFavorite
jacksum -a sha1 -m MyFavorite > websites.jacksum

2. Check frequently: Download the page again and check the web page content's checksum against the checksum you have stored previously.
wget http://www.jonelo.de/java/index.html -O MyFavorite
jacksum -c websites.jacksum
[OK]   MyFavorite

3. To fresh up the checksum in file website.jacksum, just repeat step 1 again.

As Jacksum can store multiple checksums in a .jacksum file, you can build your own website content change detection system for all your favorite websites on the net. Use scripts and cronjobs to make life easier. If your wget-download triggers a change on a webpage (a text counter for example), you will be informed about the change that you have caused. To avoid this problem, you must cut off this information from the file, before you calculate a checksum from the file (use grep -v or regular expressions for this task).

I have a problem with Jacksum that is not listed here. Can you help me?

Sure, please go to the support section.

 

Error messages

[GNU/Linux, Unix] I got bash: !": event not found

jacksum -a crc32 -q "txt:Hello World!" gives me:
bash: !": event not found

Actually this is a bash shell issue. The ! in bash has a special meaning by default, it is the history expansion character. You can reproduce it also with echo.

$ echo "!"
bash: !: event not found

$ echo "\!"
\!

$ echo \!
!

Therefore the correct usage is

jacksum -a crc32 -q "txt:Hello World"\!
472456355    12

However, this syntax is not very comfortable. Fortunately using single quotes will also solve the trouble:

$ echo '!'
!

jacksum -a crc32 -q 'txt:Hello World!'
472456355    12

See also the manpage of bash "Enclosing characters in single quotes preserves the literal value of each character whithin the quotes".


 

Developer questions

Do you have any code examples of using the Jacksum package in another tool?

Yes, the quintessential snippet is here:
 


   import java.io.*;
   import java.security.*;
   import jonelo.jacksum.*;
   import jonelo.jacksum.algorithm.*;
   // ...

   AbstractChecksum checksum = null;
   try {
     // select an algorithm (md5 in this case)
     checksum = JacksumAPI.getChecksumInstance("md5");
     // On some systems you get a better performance for particular
     // algorithms if you select an alternate algorithm (see also option -A)
     // checksum = JacksumAPI.getChecksumInstance("md5", true);
   } catch (NoSuchAlgorithmException nsae) {
     // algorithm doesn't exist
   }

   // updates the checksum with the content of a file
   try {
     checksum.readFile(filename);
   } catch (IOException ioe) {
     // ...
   }
   System.out.println(checksum);
 

To update the checksum with bytes or bytearrays, you can use the update methods:
 


   // reset the object for reuse (any formatting rules remain)
   checksum.reset();
   // update the checksum with a single byte
   checksum.update(abyte);
   // update the checksum with a bytearray
   checksum.update(bytearray);
   // update the checksum with the first 10 bytes in the bytearray
   checksum.update(bytearray, 0, 10);

   System.out.println(checksum);
 

To get the information what algorithms are supported, use the following snippet. If you use JSE 5.0 or above, you can use Generics to avoid the castings.
 


   Map map = JacksumAPI.getAvailableAlgorithms();
   Iterator iterator = map.entrySet().iterator();
   while (iterator.hasNext()) {
       Map.Entry entry = (Map.Entry)iterator.next();

       String description = (String)entry.getValue();
       // do something with the description
       // ...

       AbstractChecksum checksum = JacksumAPI.getChecksumInstance((String)entry.getKey());
       // do something with the checksum object
       // ...
   }
 

To control the format of the checksum only, you can perform methods on the checksum object:
 


   // checksum is printed in hex form (see also option -x)
   // example: 7d93370d5ef94450151826ca20c6e512
   checksum.setEncoding(HEX);

   // checksum is printed in uppercase hex form (see also option -X)
   // example: 7D93370D5EF94450151826CA20C6E512
   checksum.setEncoding(HEX_UPPERCASE);

   // checksum is printed in uppercase hex and grouped form (see also options -g, -G)
   // example: 7D93-370D-5EF9-4450-1518-26CA-20C6-E512
   checksum.setEncoding(HEX_UPPERCASE);
   checksum.setGrouping(2, '-');

   // checksum is printed in Base 64 form (see also option -E)
   // There is also BASE16 and BASE32
   // example: fZM3DV75RFAVGCbKIMblEg==
   checksum.setEncoding(BASE64);

   // checksum is printed in BubbleBabble form (see also option -E)
   // example: xizen-fetab-tilaz-necuh-buhyc-mynys-pemes-kunyc-daxox
   checksum.setEncoding(BUBBLEBABBLE);
 

To control the format of a complete line, you can use the format method
 


   // print the checksum, the default output format depends on the algorithm
   System.out.println(checksum);

   // print the checksum, the default output format depends on the algorithm
   checksum.setSeparator(";");
   System.out.println(checksum);

   // print the checksum value only (see also option -F)
   System.out.println(checksum.format("#CHECKSUM"));

   // print the checksum value with a customized format (see also option -F)
   System.out.println(checksum.format("<a href=\"ed2k://|file|#FILENAME|#FILESIZE|#FINGERPRINT|\">#FILENAME</a>"));
 

The examples above are expected to help you to take the first barriers. For detailed information about all possibilities you have with Jacksum, please have a look in the open source code or generate the javadoc from it.

 

Legal questions


What license is used by Jacksum?

The software is copyrighted and it has been released under the conditions of the GPL v2 or later.

Why the GPL ?

The license gives you the freedom to run the program, for any purpose, to study how the program works, and adapt it to your needs, to redistribute copies, and to improve the program, and release your improvements to the public. The GPL guarantees those freedoms, because you are required to license your work under the same license if you adapt the work. 


Can I incorporate Jacksum into my project?

Yes, but Jacksum is not "public domain", and Jacksum is not "freeware". Jacksum is free software which is compliant with the Free Software Foundation idea. Jacksum is distributed under the terms of the GNU General Public License (GPL), as published by the Free Software Foundation (FSF) - GPLv2 or later. If you develop a program that is based on Jacksum, the program must be compatible with the GPL. It is against all policies, if you use Jacksum's source code, and put it in a closed source project, and/or claim it as yours. Jacksum's sources are free and must be free for ever, and you should respect this freedom. Once you have understand the advantages of openess, you have done a step to a greater world.


Can I use the name Jacksum for my own project/website?

No. The name Jacksum is not part of any dictionary, it is my own creation actually. The name has been published in July 2002. The name Jacksum is copyright protected by German law and I encourage everyone to respect that law. Jacksum's source code however has been published under the conditions of the GPL so everybody can use the code.


Is it ok to publish the application on CD-ROM and DVDs?

Yes, absolutely.


Download

Highlights

The Team

The long list of contributors can always be found in the latest download package and in the copyright section. The founder and lead for this project is Johann N. Löfflmann from Germany. Since 2002 he has been working with very talented people all around the world in order to improve Jacksum further.

OSI certified
Get Java Software