Sphlib is a set of implementations of various hash functions, both in C
and in Java. The C code is meant to be easily imported into other
projects, in particular embedded systems. The Java code implements
an API somewhat similar to that of java.security.MessageDigest.
The C source code provides also two standalone tools:
- sphspeed performs speed tests on various hash functions
- sphsum computes and verifies checksums over files
Licensing is specified in the LICENSE.txt file. This is an MIT-like,
BSD-like open-source license. Basically, we will get the fame but not
the blame. If you reuse our code in your own projects, and distribute
the result, then you should state that you used our code and that we
always disclaimed any kind of warranty, and will continue to do so in
the foreseeable future, and beyond. You have no other obligation such as
disclosing your own source code. See the LICENSE.txt file for the
details in a lawyer-compatible language.
The authors are the "Projet RNRT SAPHIR", which is a research project
sponsored by the French government; project members are public and
- Ecole Normale Superieure
- France Telecom
Most of the actual code has been written by:
Thomas Pornin <email@example.com>
to whom technical questions may be addressed. Note that I do not claim
authorship: all writing was done on behalf of the Projet RNRT SAPHIR.
The programming interface for both the C code and the Java code can be
found in the doc/ subdirectory. This documentation is in HTML format and
was generated from the comments in the source code with, respectively,
doxygen and javadoc.
Installation (C code)
The c/ subdirectory contain the C code. In that directory, there are two
Makefiles and a build shell script. The shell script, named "build.sh",
is for Unix-like systems.
sphlib does not feature a "proper" compilation and configuration systems
such as those customarily found in open-source libraries for Unix
systems. This should be corrected in a future version. Right now, I am
not utterly convinced that the autoconf-generated scripts are the "way
to go". Anyway, sphlib is meant for evaluation, research and import into
other projects; a streamlined standalone compilation process is hardly
relevant for those usages.
If you happen to have a Unix-like system (e.g. Linux), you may simply
- compile the library
- compile the tools
- compile the unit tests
- run the unit tests
The library and tools may be installed with:
which will install sphspeed and sphsum in /usr/local/bin, libsph.a in
/usr/local/lib, and the header files (all the sph_*.h files) in
The installation directories and the compilation options can be altered
at will with appropriate options. Use:
to access the list of options.
"build.sh" is only for Unix-like systems such as Linux. This script has
not been thoroughly tested, is very crude, and has only very limited
autodetection capabilities. If you are after getting the maximum hashing
speed, or if you want to use the library from a shared object, you will
probably have to specify other compile options. Use "--with-cflags" to
change the compilation options. For instance:
c/build.sh --with-cflags="-W -Wall -O2 -fPIC -mtune=athlon64"
This selects options for position-independant code, i.e. suitable for
a shared object, and tuned for maximum performance on Ahtlon64-type
"build.sh" is not mandatory; you may edit and use the Makefile.unix file
The "sphsum" binary can be used to hash files in a way similar to what
the "md5sum" Linux tool does. The first argument of sphsum must be the
name of a hash function; matching is not case sensitive. Recognized
haval128_3 HAVAL, 128-bit output, 3 passes
haval128_4 HAVAL, 128-bit output, 4 passes
haval128_5 HAVAL, 128-bit output, 5 passes
haval160_3 HAVAL, 160-bit output, 3 passes
haval160_4 HAVAL, 160-bit output, 4 passes
haval160_5 HAVAL, 160-bit output, 5 passes
haval192_3 HAVAL, 192-bit output, 3 passes
haval192_4 HAVAL, 192-bit output, 4 passes
haval192_5 HAVAL, 192-bit output, 5 passes
haval224_3 HAVAL, 224-bit output, 3 passes
haval224_4 HAVAL, 224-bit output, 4 passes
haval224_5 HAVAL, 224-bit output, 5 passes
haval256_3 HAVAL, 256-bit output, 3 passes
haval256_4 HAVAL, 256-bit output, 4 passes
haval256_5 HAVAL, 256-bit output, 5 passes
ripemd RIPEMD (original function)
ripemd128 RIPEMD-128 (revised function, 128-bit output)
ripemd160 RIPEMD-160 (revised function, 160-bit output)
rmd RIPEMD (original function)
rmd128 RIPEMD-128 (revised function, 128-bit output)
rmd160 RIPEMD-160 (revised function, 160-bit output)
sha0 SHA-0 (original SHA, withdrawn)
tiger2 Tiger2 (Tiger with a modified padding)
whirlpool Whirlpool (2003, current version)
whirlpool0 Whirlpool-0 (2000)
whirlpool1 Whirlpool-1 (2001)
Alternatively, the "sphsum" executable file can be named after one of
these functions, in which case the function name needs not be specified.
Hence, if you install "sphsum" and create a link (either symbolic or
not) to "sphsum" named "md5sum", then you may use that link as a drop-in
replacement for the standard Linux tool "md5sum". This function name
recognition process ignores the ".exe", "sum" and "sum.exe" suffixes.
On Windows systems, you may use the Makefile.win32 file. This is meant
for Visual C (command-line compiler). Open a "Visual C console" from the
start menu (this is a standard text console with the environment set up
for using cl.exe). Type:
nmake /f makefile.win32
which should compile the code, the unit tests and the standalone
binaries. There is no library per se, only a collection of object files.
Other C compilers exist for Windows (e.g. MinGW or the cygwin system).
If you wish to include sphlib C code in your own projects, then you must
copy the following files:
- all the sph_*.h header files
- the following C files:
The other source code files are for the standalone tools, and the unit
Most of the "magic" happens in sph_types.h. This is where one may find
such things as inline assembly for faster little/big-endian word access.
Installation (Java code)
Java code is in the java/ directory. Hash function implementations are
located in the "fr.cryptohash" package; there is one specific class for
each hash function, a common interface called "Digest", and some
non-public helper classes.
The "fr.cryptohash.test" package contains two standalone applications
(classes with a main() method). The "TestDigest" application runs the
unit tests. The "Speed" application runs speed tests, with an output
similar to that provided by the "sphspeed" tool from the C code. Note
that these tests cannot access the CPU usage by the test process; hence,
speed tests should be performed on an otherwise idle machine.
The Java code should be compatible both with older virtual machine
(e.g. Java 1.1) and with J2ME platforms.
The NIST SHA-3 API
Internally, sphlib tends to use the name "sha3" for the 64-bit functions
of the SHA-2 family, namely SHA-384 and SHA-512. This is historical.
Here, we talk about the SHA-3 contest which was launched in 2008 by
NIST, to define the next family of hash functions which will become an
american standard, as substitutes for the existing SHA-224, SHA-256,
SHA-384 and SHA-512 functions. Many candidate functions have been
submitted so far. One such candidate is SHABAL, which sphlib implements.
For the purposes of this competition, the NIST published a C API. All
candidates were asked to provide reference and optimized implementations
fitting in that API.
The basic sphlib API is different from the NIST API. However, a
compatibility layer has been added to sphlib-1.1. It consists of the
sha3nist.c and sha3nist.h source files. With these files, you may use
some of the sphlib implementations through an API conforming to the NIST
specification. Namely, you may select either the SHA-224/256/384/512
family, or SHABAL.
To use that layer, modify sha3nist.h to designate the hash functions
you wish to use. By default, the SHA-224/... functions are used. To
use SHABAL instead, replace the following three lines:
#define SPH_NIST sha
#define SPH_NIST shabal
And add the sha3nist.c file to the list of C files to compile into your
As of version 1.1, only the standard SHA-224/... functions, and SHABAL,
may use this layer. It is expected that future versions of sphlib will
include implementations for other SHA-3 candidates, which will be usable
through the NIST compatibility layer as well.
Future versions of sphlib will feature:
- other hash functions
- options for better conditional inclusion (e.g. not compiling RIPEMD if
you only want RIPEMD-160)
- optimized versions for footprint-constrained environments (which should
also help platforms with a small L1 cache)
- a better compilation and installation procedure for the library and
- man pages for the standalone tools
- a building process for sphlib as a shared library
** new in sphlib-1.1
- Fixed bug in Panama implementation (some special padding cases)
- Added RadioGatun and RadioGatun (C)
- Added SHABAL-192/224/256/384/512 (C and Java)
- Added API for fractional bits on some functions (MD5, SHA-0, SHA-1,
SHA-224/256/384/512 and SHABAL)
- Added compatibility layer for the NIST SHA-3 competition API