fysxasteroids/engine/libraries/sha2/README

VERSION:

This is version 1.0 RELEASE

While this is my "release" version, due to lack of additional
official test vectors against which to verify this implementation's
correctness, beware that there may be implementation bugs.  Also,
it has not yet been tested on very many other architectures,
big-endian machines in particular.


LICENSE:

This implementation is released freely under an open-source BSD
license which appears at the top of each source code file.


WHAT IT IS:

The files sha2.h and sha2.c implement the SHA-256, SHA-384, and SHA-512
hash algorithms as described in the PDF document found at the following
web address:

  http://csrc.nist.gov/cryptval/shs/sha256-384-512.pdf

The interface is similar to the interface to SHA-1 found in the OpenSSL
library.

The file sha2prog.c is a simple program that accepts input from either
STDIN or reads one or more files specified on the command line, and then
generates the specified hash (either SHA-256, SHA-384, SHA-512, or any
combination thereof, including all three at once).


LIMITATIONS:

This implementation has several limitations:

 * Input data is only accepted in octet-length increments.  No sub-byte
   data is handled.  The NIST document describes how to handle sub-byte
   input data, but for ease of implementation this version will only
   accept message data in multiples of bytes.
 * This implementation utilizes 64-bit integer data types.  If your
   system and compiler does not have a 64-bit integer data type, this
   implementation will not work.
 * Because of the use of 64-bit operations, many 32-bit architectures
   that do have 64-bit data types but do operations most efficiently
   on 32-bit words, this implementation may be slower than an
   implementation designed to use only 32-bit words (emulating the
   64-bit operations).
 * On platforms with 128-bit integer data types, the SHA-384 and SHA-512
   bit counters used by this implementation might be better off using
   the 128-bit type instead of simulating it with two 64-bit integers.
 * This implementation was written in C in hopes of portability and for
   the fun of it during my spare time.  It is probably not the most
   efficient or fastest C implementation.  I welcome suggestions,
   however, that suggest ways to speed things up without breaking
   portability.  I also welcome suggestions to improve portability.
 * As mentioned above, this code has NOT been thoroughly tested.
   This is perhaps the most severe limitation.


BEFORE YOU COMPILE (OPTIONS):

Each of the options described below may either be defined in the sha2.h
header file (or in the sha2.c file in some cases), or on the command
line at compile time if your compiler supports such things.  For
example:

  #define SHA2_USE_INTTYPES_H
  #define SHA2_UNROLL_TRANSFORM

Or:

  cc -c -DSHA2_UNROLL_TRANSFORM sha2.c
  cc -c -DBYTE_ORDER=4321 -DBIG_ENDIAN=4321 sha2.c

Here are the available options.  Read on below for a description of
each one:

  SHA2_USE_INTTYPES_H
  SHA2_USE_MEMSET_MEMCPY/SHA2_USE_BZERO_BCOPY
  SHA2_UNROLL_TRANSFORM
  BYTE_ORDER (LITTLE_ENDIAN/BIG_ENDIAN)

* SHA2_USE_INTTYPES_H option:
By default, this code uses u_intXX_t data types for 8 bit, 32 bit, and
64 bit unsigned integer type definitions.  Most BSD systems define these,
as does Linux.  However, some (like Compaq's Tru64 Unix) may instead
use uintXX_t data types as defined by recent ANSI C standards and as
included in the inttypes.h header file.  Those wanting to use inttypes.h
need to define this either in sha.h or at compile time.

On those systems where NEITHER definitions are available, you will need
to edit both sha2.h and sha2.c and define things by hand in the appropriate
sections.

* BYTE_ORDER definitions:
This code assumes that BYTE_ORDER will be defined by the system during
compile to either equal LITTLE_ENDIAN or BIG_ENDIAN.  If your system
does not define these, you may need to define them by hand in the sha.c
file according to the byte ordering conventions of your system.

* SHA2_USE_MEMSET_MEMCPY or SHA2_USE_BZERO_BCOPY
The code in sha2.c can use either memset()/memcpy() for memory block
operations, or bzero()/mcopy().  If you define neither of these, the
code will default to memset()/memcpy().  You can define either at the
command line or in sha2.h or in sha2.c.

* SHA2_UNROLL_TRANSFORM
By defining this either on the command line or in sha2.h or sha2.c,
the code will use macros to partially "unroll" the SHA transform
function.  This usually generates bigger executables.  It CAN (but
not necessarily WILL) generate faster code when you tell your compiler
to optimize things.  For example, on the FreeBSD and Linux x86 systems
I tested things on (using gcc), when I optimized with just -O2 and
unrolled the transform, the hash transform was faster by 15-30%.  On
these same systems, if I did NO optimization, the unrolled transform
was SLOWER, much slower (I'm guessing because the code was breaking
the cache, but I'm not sure).  Your mileage may vary.


PORTABILITY:

The code in sha2.c and sha2.h is intended to be portable.  It may
require that you do a few #definitions in the .h file.  I've successfully
compiled and tested the sha2.c and sha2.h code on Apple's OS X (on
a PPC), FreeBSD 4.1.1 on Intel, Linux on Intel, FreeBSD on the Alpha,
and even under Windows98SE using Metrowerks C.  The utility/example
programs (sha2prog.c, sha2test.c, and sha2speed.c) will very likely
have more trouble in portability since they do I/O.

To get sha2.c/sha2.h working under Windows, I had to define
SHA2_USE_INTTYPES_H, BYTE_ORDER, LITTLE_ENDIAN, and had to comment
out the include of <sys/types.h> in sha2.h.  With a bit more work
I got the test program to run and verified that all the test
cases passed.


SUGGESTIONS/BUG FIXES:

If you make changes to get it working on other architectures, if you fix
any bugs, or if you make changes that improve this implementation's
efficiency that would be relatively portable and you're willing to release
your changes under the same license, please send them to me for possible
inclusion in future versions.

If you know where I can find some additional test vectors, please let me
know.


CHANGE HISTORY:

0.8 to 0.9 	- Fixed spelling errors, changed to u_intXX_t type usage,
		  removed names from prototypes, added prototypes to sha2.c,
		  and a few things I can't recall.

0.9 to 0.9.5	- Add a new define in sha2.c that permits one to compile
		  it to either use memcpy()/memset() or bcopy()/bzero()
		  for memory block copying and zeroing.  Added support
		  for unrolled SHA-256/384/512 transform loops.  Just
		  compile with SHA2_UNROLL_TRANSFORM to enable.  It takes
		  longer to compile, but I hope it is a bit faster.  I
		  need to do some test to see whether or not it is. Oh,
		  in sha2.c, you either need to define SHA2_USE_BZERO_BCOPY
		  or SHA2_USE_MEMSET_MEMCPY to choose which way you want
		  to compile.  *Whew*  It's amazing how quickly something
		  simple starts to grow more complex even in the span of
		  just a few hours.  I didn't really intend to do this much.
0.9.5 to 0.9.6  - Added a test program (sha2test) which tests against several
                  known test vectors.  WARNING: Some of the test output
                  hashes are NOT from NIST's documentation and are the
                  output of this implementation and so may be incorrect.
0.9.6 to 0.9.7  - Fixed a bug that could cause invalid output in certain
		  cases and added an assumed scenario where zero-length
		  data is hashed.  Also changed the rotation macros to use
		  a temporary variable as this reduces the number of operations.
		  When data is fed in blocks of the right length, copying of
		  data is reduced in this version.  Added SHAYXZ_Data()
		  functions for ease of hashing a set of data.  Added another
		  file sha2speed.c for doing speed testing.  Added another test
		  vector with a larger data size (16KB).  Fixed u_intXX_t and
		  uintXX_t handling by adding a define for SHA2_USE_INTTYPES_H
		  as well as made a few other minor changes to get rid of
		  warnings when compiling on Compaq's Tru64 Unix.
0.9.7 to 0.9.8  - The bug fix in 0.9.7 was incomplete and in some cases made
                  things worse.  I believe that 0.9.8 fixes the bug completely
                  so that output is correct.  I cannot verify this, however,
                  because of the lack of test vectors against which to do such
                  verification.  All versions correctly matched the very few
                  NIST-provided vectors, but unfortunately the bug only
                  appeared in longer message data sets.
0.9.8 to 0.9.9  - Fixed some really bad typos and mistakes on my part that
                  only affected big-endian systems.  I didn't have direct
                  access for testing before this version.  Thanks to
                  Lucas Marshall for giving me access to his OS X system.
0.9.9 to 1.0.0b1  Added a few more test samples and made a few changes to
                  make things easier compiling on several other platforms.
                  Also I experimented with alternate macro definitions
                  in the SHA2_UNROLL_TRANSFORM version (see sha2.slower.c)
                  and eliminated the T1 temporary variable (the compiler
                  would of course still use internal temporary storage
                  during expression evaluation, but I'd hoped the compiler
                  would be more efficient), but unfortunately under FreeBSD
                  4.1.1-STABLE on an x86 platform, the change slowed things
                  down.
1.0.0b1 to 1.0 RELEASE  Fixed an off-by-one implementation bug that affected
                  SHA-256 when hashed data length L = 55 + 64 * X where X is
                  either zero or a positive integer, and another (basically
                  the same bug) bug in SHA-384 and SHA-512 that showed up when
                  hashed data lengths L = 111 + 128 * X.  Thanks to Rogier
		  van de Pol for sending me test data that revealed the bug.
                  The fix was very simple (just two tiny changes).  Also,
                  I finally put the files into RCS so future changes will be
                  easier to manage.  The sha2prog.c file was rewritten to
                  be more useful to me, and I got rid of the old C testing
                  program and now use a perl script with a subdirectory full
                  of test data.  It's a more flexible test system.


LATEST VERSION:

The latest version and documentation (if any ;) should always be available
on the web at:

  http://www.aarongifford.com/computers/sha.html


CONTACT ME:

I can be reached via email at:

  Aaron Gifford   <m e @ a a r o n g i f f o r d . c o m>

Please don't send support questions.  I don't have the time to answer and
they'll probably be ignored.  Bug fixes, or patches that add something useful
will be gratefully accepted, however.

If you use this implementation, I would enjoy getting a brief email message
letting me know who you are and what use to which it is being put.  There
is no requirement to do so.  I just think it would be fun.


EXAMPLES:

Here's an example of compiling and using the sha2 program (in this example
I build it using the unrolled transform version with -O2 optimizations),
and then running the perl testing script:

  cc -O2 -DSHA2_UNROLL_TRANSFORM -Wall -o sha2 sha2prog.c sha2.c
  % ./sha2test.pl

  [most of the perl script output deleted for brevity]

  ===== RESULTS (18 VECTOR DATA FILES HASHED) =====

  HASH TYPE       NO. OF TESTS    PASSED  FAILED
  ---------       ------------    ------  ------
  SHA-256                   18        18       0
  SHA-384                   18        18       0
  SHA-512                   18        18       0
  ----------------------------------------------
  TOTAL:                    54        54       0

  NO ERRORS!  ALL TESTS WERE SUCCESSFUL!

  ALL TEST VECTORS PASSED!

That's all folks!  Have fun!

Aaron out.