extlibs/tinydtls/sha2/README

   1 VERSION:
   2
   3 This is version 1.0 RELEASE
   4
   5 While this is my "release" version, due to lack of additional
   6 official test vectors against which to verify this implementation's
   7 correctness, beware that there may be implementation bugs.  Also,
   8 it has not yet been tested on very many other architectures,
   9 big-endian machines in particular.
  10
  11
  12 LICENSE:
  13
  14 This implementation is released freely under an open-source BSD
  15 license which appears at the top of each source code file.
  16
  17
  18 WHAT IT IS:
  19
  20 The files sha2.h and sha2.c implement the SHA-256, SHA-384, and SHA-512
  21 hash algorithms as described in the PDF document found at the following
  22 web address:
  23
  24   http://csrc.nist.gov/cryptval/shs/sha256-384-512.pdf
  25
  26 The interface is similar to the interface to SHA-1 found in the OpenSSL
  27 library.
  28
  29 The file sha2prog.c is a simple program that accepts input from either
  30 STDIN or reads one or more files specified on the command line, and then
  31 generates the specified hash (either SHA-256, SHA-384, SHA-512, or any
  32 combination thereof, including all three at once).
  33
  34
  35 LIMITATIONS:
  36
  37 This implementation has several limitations:
  38
  39  * Input data is only accepted in octet-length increments.  No sub-byte
  40    data is handled.  The NIST document describes how to handle sub-byte
  41    input data, but for ease of implementation this version will only
  42    accept message data in multiples of bytes.
  43  * This implementation utilizes 64-bit integer data types.  If your
  44    system and compiler does not have a 64-bit integer data type, this
  45    implementation will not work.
  46  * Because of the use of 64-bit operations, many 32-bit architectures
  47    that do have 64-bit data types but do operations most efficiently
  48    on 32-bit words, this implementation may be slower than an
  49    implementation designed to use only 32-bit words (emulating the
  50    64-bit operations).
  51  * On platforms with 128-bit integer data types, the SHA-384 and SHA-512
  52    bit counters used by this implementation might be better off using
  53    the 128-bit type instead of simulating it with two 64-bit integers.
  54  * This implementation was written in C in hopes of portability and for
  55    the fun of it during my spare time.  It is probably not the most
  56    efficient or fastest C implementation.  I welcome suggestions,
  57    however, that suggest ways to speed things up without breaking
  58    portability.  I also welcome suggestions to improve portability.
  59  * As mentioned above, this code has NOT been thoroughly tested.
  60    This is perhaps the most severe limitation.
  61
  62
  63 BEFORE YOU COMPILE (OPTIONS):
  64
  65 Each of the options described below may either be defined in the sha2.h
  66 header file (or in the sha2.c file in some cases), or on the command
  67 line at compile time if your compiler supports such things.  For
  68 example:
  69
  70   #define SHA2_USE_INTTYPES_H
  71   #define SHA2_UNROLL_TRANSFORM
  72
  73 Or:
  74
  75   cc -c -DSHA2_UNROLL_TRANSFORM sha2.c
  76   cc -c -DBYTE_ORDER=4321 -DBIG_ENDIAN=4321 sha2.c
  77
  78 Here are the available options.  Read on below for a description of
  79 each one:
  80
  81   SHA2_USE_INTTYPES_H
  82   SHA2_USE_MEMSET_MEMCPY/SHA2_USE_BZERO_BCOPY
  83   SHA2_UNROLL_TRANSFORM
  84   BYTE_ORDER (LITTLE_ENDIAN/BIG_ENDIAN)
  85
  86 * SHA2_USE_INTTYPES_H option:
  87 By default, this code uses u_intXX_t data types for 8 bit, 32 bit, and
  88 64 bit unsigned integer type definitions.  Most BSD systems define these,
  89 as does Linux.  However, some (like Compaq's Tru64 Unix) may instead
  90 use uintXX_t data types as defined by recent ANSI C standards and as
  91 included in the inttypes.h header file.  Those wanting to use inttypes.h
  92 need to define this either in sha.h or at compile time.
  93
  94 On those systems where NEITHER definitions are available, you will need
  95 to edit both sha2.h and sha2.c and define things by hand in the appropriate
  96 sections.
  97
  98 * BYTE_ORDER definitions:
  99 This code assumes that BYTE_ORDER will be defined by the system during
 100 compile to either equal LITTLE_ENDIAN or BIG_ENDIAN.  If your system
 101 does not define these, you may need to define them by hand in the sha.c
 102 file according to the byte ordering conventions of your system.
 103
 104 * SHA2_USE_MEMSET_MEMCPY or SHA2_USE_BZERO_BCOPY
 105 The code in sha2.c can use either memset()/memcpy() for memory block
 106 operations, or bzero()/mcopy().  If you define neither of these, the
 107 code will default to memset()/memcpy().  You can define either at the
 108 command line or in sha2.h or in sha2.c.
 109
 110 * SHA2_UNROLL_TRANSFORM
 111 By defining this either on the command line or in sha2.h or sha2.c,
 112 the code will use macros to partially "unroll" the SHA transform
 113 function.  This usually generates bigger executables.  It CAN (but
 114 not necessarily WILL) generate faster code when you tell your compiler
 115 to optimize things.  For example, on the FreeBSD and Linux x86 systems
 116 I tested things on (using gcc), when I optimized with just -O2 and
 117 unrolled the transform, the hash transform was faster by 15-30%.  On
 118 these same systems, if I did NO optimization, the unrolled transform
 119 was SLOWER, much slower (I'm guessing because the code was breaking
 120 the cache, but I'm not sure).  Your mileage may vary.
 121
 122
 123 PORTABILITY:
 124
 125 The code in sha2.c and sha2.h is intended to be portable.  It may
 126 require that you do a few #definitions in the .h file.  I've successfully
 127 compiled and tested the sha2.c and sha2.h code on Apple's OS X (on
 128 a PPC), FreeBSD 4.1.1 on Intel, Linux on Intel, FreeBSD on the Alpha,
 129 and even under Windows98SE using Metrowerks C.  The utility/example
 130 programs (sha2prog.c, sha2test.c, and sha2speed.c) will very likely
 131 have more trouble in portability since they do I/O.
 132
 133 To get sha2.c/sha2.h working under Windows, I had to define
 134 SHA2_USE_INTTYPES_H, BYTE_ORDER, LITTLE_ENDIAN, and had to comment
 135 out the include of <sys/types.h> in sha2.h.  With a bit more work
 136 I got the test program to run and verified that all the test
 137 cases passed.
 138
 139
 140 SUGGESTIONS/BUG FIXES:
 141
 142 If you make changes to get it working on other architectures, if you fix
 143 any bugs, or if you make changes that improve this implementation's
 144 efficiency that would be relatively portable and you're willing to release
 145 your changes under the same license, please send them to me for possible
 146 inclusion in future versions.
 147
 148 If you know where I can find some additional test vectors, please let me
 149 know.
 150
 151
 152 CHANGE HISTORY:
 153
 154 0.8 to 0.9      - Fixed spelling errors, changed to u_intXX_t type usage,
 155                   removed names from prototypes, added prototypes to sha2.c,
 156                   and a few things I can't recall.
 157
 158 0.9 to 0.9.5    - Add a new define in sha2.c that permits one to compile
 159                   it to either use memcpy()/memset() or bcopy()/bzero()
 160                   for memory block copying and zeroing.  Added support
 161                   for unrolled SHA-256/384/512 transform loops.  Just
 162                   compile with SHA2_UNROLL_TRANSFORM to enable.  It takes
 163                   longer to compile, but I hope it is a bit faster.  I
 164                   need to do some test to see whether or not it is. Oh,
 165                   in sha2.c, you either need to define SHA2_USE_BZERO_BCOPY
 166                   or SHA2_USE_MEMSET_MEMCPY to choose which way you want
 167                   to compile.  *Whew*  It's amazing how quickly something
 168                   simple starts to grow more complex even in the span of
 169                   just a few hours.  I didn't really intend to do this much.
 170 0.9.5 to 0.9.6  - Added a test program (sha2test) which tests against several
 171                   known test vectors.  WARNING: Some of the test output
 172                   hashes are NOT from NIST's documentation and are the
 173                   output of this implementation and so may be incorrect.
 174 0.9.6 to 0.9.7  - Fixed a bug that could cause invalid output in certain
 175                   cases and added an assumed scenario where zero-length
 176                   data is hashed.  Also changed the rotation macros to use
 177                   a temporary variable as this reduces the number of operations.
 178                   When data is fed in blocks of the right length, copying of
 179                   data is reduced in this version.  Added SHAYXZ_Data()
 180                   functions for ease of hashing a set of data.  Added another
 181                   file sha2speed.c for doing speed testing.  Added another test
 182                   vector with a larger data size (16KB).  Fixed u_intXX_t and
 183                   uintXX_t handling by adding a define for SHA2_USE_INTTYPES_H
 184                   as well as made a few other minor changes to get rid of
 185                   warnings when compiling on Compaq's Tru64 Unix.
 186 0.9.7 to 0.9.8  - The bug fix in 0.9.7 was incomplete and in some cases made
 187                   things worse.  I believe that 0.9.8 fixes the bug completely
 188                   so that output is correct.  I cannot verify this, however,
 189                   because of the lack of test vectors against which to do such
 190                   verification.  All versions correctly matched the very few
 191                   NIST-provided vectors, but unfortunately the bug only
 192                   appeared in longer message data sets.
 193 0.9.8 to 0.9.9  - Fixed some really bad typos and mistakes on my part that
 194                   only affected big-endian systems.  I didn't have direct
 195                   access for testing before this version.  Thanks to
 196                   Lucas Marshall for giving me access to his OS X system.
 197 0.9.9 to 1.0.0b1  Added a few more test samples and made a few changes to
 198                   make things easier compiling on several other platforms.
 199                   Also I experimented with alternate macro definitions
 200                   in the SHA2_UNROLL_TRANSFORM version (see sha2.slower.c)
 201                   and eliminated the T1 temporary variable (the compiler
 202                   would of course still use internal temporary storage
 203                   during expression evaluation, but I'd hoped the compiler
 204                   would be more efficient), but unfortunately under FreeBSD
 205                   4.1.1-STABLE on an x86 platform, the change slowed things
 206                   down.
 207 1.0.0b1 to 1.0 RELEASE  Fixed an off-by-one implementation bug that affected
 208                   SHA-256 when hashed data length L = 55 + 64 * X where X is
 209                   either zero or a positive integer, and another (basically
 210                   the same bug) bug in SHA-384 and SHA-512 that showed up when
 211                   hashed data lengths L = 111 + 128 * X.  Thanks to Rogier
 212                   van de Pol for sending me test data that revealed the bug.
 213                   The fix was very simple (just two tiny changes).  Also,
 214                   I finally put the files into RCS so future changes will be
 215                   easier to manage.  The sha2prog.c file was rewritten to
 216                   be more useful to me, and I got rid of the old C testing
 217                   program and now use a perl script with a subdirectory full
 218                   of test data.  It's a more flexible test system.
 219
 220
 221 LATEST VERSION:
 222
 223 The latest version and documentation (if any ;) should always be available
 224 on the web at:
 225
 226   http://www.aarongifford.com/computers/sha.html
 227
 228
 229 CONTACT ME:
 230
 231 I can be reached via email at:
 232
 233   Aaron Gifford   <m e @ a a r o n g i f f o r d . c o m>
 234
 235 Please don't send support questions.  I don't have the time to answer and
 236 they'll probably be ignored.  Bug fixes, or patches that add something useful
 237 will be gratefully accepted, however.
 238
 239 If you use this implementation, I would enjoy getting a brief email message
 240 letting me know who you are and what use to which it is being put.  There
 241 is no requirement to do so.  I just think it would be fun.
 242
 243
 244 EXAMPLES:
 245
 246 Here's an example of compiling and using the sha2 program (in this example
 247 I build it using the unrolled transform version with -O2 optimizations),
 248 and then running the perl testing script:
 249
 250   cc -O2 -DSHA2_UNROLL_TRANSFORM -Wall -o sha2 sha2prog.c sha2.c
 251   % ./sha2test.pl
 252
 253   [most of the perl script output deleted for brevity]
 254
 255   ===== RESULTS (18 VECTOR DATA FILES HASHED) =====
 256
 257   HASH TYPE       NO. OF TESTS    PASSED  FAILED
 258   ---------       ------------    ------  ------
 259   SHA-256                   18        18       0
 260   SHA-384                   18        18       0
 261   SHA-512                   18        18       0
 262   ----------------------------------------------
 263   TOTAL:                    54        54       0
 264
 265   NO ERRORS!  ALL TESTS WERE SUCCESSFUL!
 266
 267   ALL TEST VECTORS PASSED!
 268
 269 That's all folks!  Have fun!
 270
 271 Aaron out.
 272